Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "miakapi",
"version": "4.5.1",
"version": "4.6.0",
"description": "Typed coordinator and trusted-browser SDK for Miakapp",
"type": "module",
"packageManager": "bun@1.2.23",
Expand Down
19 changes: 13 additions & 6 deletions packages/cli/assets/members.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,15 @@ What Miakapp gives you:

Anyone signed in can open any home's address and load its app (the bundle holds
no household data: §5 of `docs start`). A person you have not admitted must get
**nothing** from the coordinator: no state path, no event, every function
refused except the few a visitor needs (asking to join, redeeming an invite).
**nothing** from the coordinator: no state path, no event, no function.

**A visitor can call one function only: `miakapp.join`.** The relay refuses
every other call from an account that no `stateAccess`/`eventAccess` entry
names (code 1201, the app only sees `failed`). So the visitor's door is a
single function your coordinator declares (miakapi ≥ 4.6.0), taking an
action: `miakapp.join({ action: 'me' | 'request' | 'redeem', … })`. Your app
calls it for "who am I", "ask to join" and "redeem this invite", for members
and visitors alike.

## What to build (the usual shape)

Expand All @@ -50,9 +57,9 @@ interface Member {
2. **Apply rights the moment the list changes**: recompute `stateAccess` and
`eventAccess` for everyone and `declareState(...)` again. A new member sees
the home without reloading; a removed one loses it at once.
3. **A visitor asks to join.** Your app calls e.g. `members.me`: a non-member
gets `{ member: false, requested: boolean }` and your app shows a "Request
to join" screen with the home's name. `members.request` records
3. **A visitor asks to join.** Your app calls `miakapp.join({ action: 'me' })`:
a non-member gets `{ member: false, requested: boolean }` and your app shows a
"Request to join" screen with the home's name. `{ action: 'request' }` records
`{ id, email, at }` (one pending request per account, refuse floods), then
`miakapp notify --to` the owner and admins: "Diana wants to join".
4. **A Members tab for those who manage.** Show the bar button only to owner and
Expand All @@ -75,7 +82,7 @@ interface Member {
the clipboard; Miakapp does it, with a copy fallback). On `'unavailable'`,
show the link in a read-only field so it can be copied by hand.
The app reads `home.link.params.invite` on start and, if present, calls
`members.redeem({ code })`. Never trust the app: the coordinator checks
`miakapp.join({ action: 'redeem', code })`. Never trust the app: the coordinator checks
everything.
6. **Roles that manage**: decide who may accept, invite and with which roles
(an admin may not create an owner or remove an admin, for example). Check it
Expand Down
5 changes: 3 additions & 2 deletions packages/cli/src/project.ts
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ export function resolveProjectPath(root: string, declared: unknown, label: strin

/**
* The trusted shell brokers only state reads and calls to a whole-house
* application, and never a protocol-reserved `miakapp.*` function. Declaring
* application, and never a protocol-reserved `miakapp.*` function but `miakapp.join`. Declaring
* anything else would publish a manifest the shell silently narrows, so it is
* refused here instead.
*/
Expand All @@ -74,7 +74,8 @@ function assertAppCeiling(requires: Requirements): void {
);
}
}
const reserved = requires.call.find((name) => name === 'miakapp.*' || name.startsWith('miakapp.'));
// `miakapp.join` is the visitors' door (docs members): the one reserved function an app calls.
const reserved = requires.call.find((name) => name === 'miakapp.*' || (name.startsWith('miakapp.') && name !== 'miakapp.join'));
if (reserved !== undefined) {
throw projectError(`app.requires.call names the protocol-reserved function ${reserved}`);
}
Expand Down
6 changes: 5 additions & 1 deletion packages/cli/test/app-publication.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,17 @@ describe('app manifest', () => {
expect(project.requires.call).toEqual(['lighting.set']);
});

test('an app may call miakapp.join, the visitors\' door', () => {
expect(parseProject(PROJECT_ROOT, APP_YAML.replace(' - lighting.set', ' - lighting.set\n - miakapp.join'))).toBeDefined();
});

test('refuses both or neither section, and anything the shell would not broker', () => {
const refused = [
APP_YAML.replace('app:', 'component:\n artifact: a.js\n release: x\napp:'),
APP_YAML.replace(/app:[\s\S]*/u, ''),
APP_YAML.replace(' call:', ' event_subscribe:\n - door.opened\n call:'),
APP_YAML.replace(' call:', ' presentation:\n - media.camera\n call:'),
APP_YAML.replace(' - lighting.set', ' - miakapp.join'),
APP_YAML.replace(' - lighting.set', ' - miakapp.direct.house'),
APP_YAML.replace(' - lighting.set', ' - miakapp.*'),
APP_YAML.replace(' release: 2026-10-03.1', ' release: 2026-10-03.1\n url: https://x'),
];
Expand Down
4 changes: 3 additions & 1 deletion src/internal/validation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,9 @@ export function validateFunctions(value: unknown): Readonly<Record<string, Funct
const budget: ValueBudget = { values: 1, bytes: 5 };
for (const name of names) {
validateStructuredName(name, `function ${name}`);
if (name === 'miakapp.join') throw new TypeError('miakapp.join is reserved');
// `miakapp.join` is the one function a signed-in visitor who is not enrolled may call
// (RFC 0001): a coordinator declares it to let people ask to join or redeem an invitation.
// The relay lets one coordinator own it.
const handler = value[name];
if (!isFunctionHandler(handler)) throw new TypeError(`function ${name} has no handler`);
accountDeclarationValue(budget, UTF8.encode(name).byteLength + 5, 'function declaration');
Expand Down
9 changes: 9 additions & 0 deletions test/declarations.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,15 @@ describe('declaration transactions', () => {
await harness.coordinator.stop();
});

test('a coordinator may declare miakapp.join, the visitors\' door', async () => {
const harness = createTestHarness();
const { connection } = await startReady(harness);
const declared = harness.coordinator.functions.declare({ 'miakapp.join': () => ({ member: false }) });
const functions = await advanceThroughFunctionHandoff(connection);
expect(names(functions.payload[1], 'FUNCTION_SYNC.names')).toContain('miakapp.join');
void declared.catch(() => undefined);
});

test('never sends direct-only state access to the relay', async () => {
const harness = createTestHarness();
const { connection } = await startReady(harness);
Expand Down
Loading