From b50c480179a77067b146c7ea275470ddcc47030f Mon Sep 17 00:00:00 2001 From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:42:49 +0100 Subject: [PATCH 1/2] feat: a coordinator may declare miakapp.join, the visitors' door (4.6.0) The relay lets an account that is not enrolled call miakapp.join only, but the SDK refused to declare it, so a home had no way to let visitors ask to join or redeem an invitation: every such call failed with 1201. The name is now declarable (the relay keeps a single owner), and docs members routes 'who am I', 'ask to join' and 'redeem' through it (CLI 4.5.3). --- package.json | 2 +- packages/cli/assets/members.md | 19 +++++++++++++------ src/internal/validation.ts | 4 +++- test/declarations.test.ts | 9 +++++++++ 4 files changed, 26 insertions(+), 8 deletions(-) diff --git a/package.json b/package.json index 4bf01ac..1713b5e 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/packages/cli/assets/members.md b/packages/cli/assets/members.md index da95b9f..b8a371c 100644 --- a/packages/cli/assets/members.md +++ b/packages/cli/assets/members.md @@ -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) @@ -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 @@ -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 diff --git a/src/internal/validation.ts b/src/internal/validation.ts index 5f72ad8..557ed63 100644 --- a/src/internal/validation.ts +++ b/src/internal/validation.ts @@ -387,7 +387,9 @@ export function validateFunctions(value: unknown): Readonly { 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); From d47ee2cba3372982016dd26dae29f38a41e56c50 Mon Sep 17 00:00:00 2001 From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:43:47 +0100 Subject: [PATCH 2/2] feat(cli): an app may call miakapp.join --- packages/cli/src/project.ts | 5 +++-- packages/cli/test/app-publication.test.ts | 6 +++++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/packages/cli/src/project.ts b/packages/cli/src/project.ts index 7d90934..a79d35f 100644 --- a/packages/cli/src/project.ts +++ b/packages/cli/src/project.ts @@ -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. */ @@ -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}`); } diff --git a/packages/cli/test/app-publication.test.ts b/packages/cli/test/app-publication.test.ts index 7e97d96..feda663 100644 --- a/packages/cli/test/app-publication.test.ts +++ b/packages/cli/test/app-publication.test.ts @@ -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'), ];