@byollm/control-plane 0.1.0-alpha.58 → 0.1.0-alpha.59

package/README.md

@@ -1,6 +1,6 @@
 # @byollm/control-plane
 
-> **Alpha (`0.1.0-alpha.58`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.59`) — under active development. Don't use this yet.**
 
 The reference control plane: it resolves a person's mapping and authors one
 signed grant per job, against a policy store it does not own and with a key it

package/dist/index.d.ts

@@ -71,8 +71,18 @@ declare class ControlPlane {
      */
     authorGrant(input: {
         readonly job: ClaimedStub;
-        /** The site's id in this control plane's namespace, not its key id. */
+        /** The site's id in this control plane's namespace, for the policy read. */
         readonly siteId: string;
+        /**
+         * The same site, as the key id the device pinned — the value that gets
+         * signed.
+         *
+         * Two ids for one site, and both are needed: the store is keyed by the
+         * control plane's own id, and the device knows sites only by what it
+         * pinned. The grant carries the one the device can check without asking
+         * anybody, which is the whole point of a signed document.
+         */
+        readonly siteKey: string;
         /** The device owner asking. */
         readonly owner: string;
         /**

package/dist/index.js

@@ -33,6 +33,9 @@ var ControlPlane = class {
     let snapshot;
     try {
       snapshot = await this.#store.read({
+        // The control plane's own id: the store is keyed by it, and the key
+        // id below is for the device. Two ids, two readers, neither
+        // substitutable for the other.
         siteId: input.siteId,
         user: job.owner,
         owner
@@ -57,7 +60,7 @@ var ControlPlane = class {
       granted: await this.#signer.sign({
         grantId: this.#newId(),
         jobId: job.id,
-        siteId: input.siteId,
+        site: input.siteKey,
         user: job.owner,
         owner,
         purpose,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/engine.ts","../src/memory.ts","../src/signer.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n  RESERVED_PURPOSE,\n  type CapabilityMatrix,\n  type ClaimedStub,\n  type SignedGrant,\n} from \"@byollm/protocol\";\nimport type { GrantSigner } from \"./signer.js\";\nimport type { PolicyStore } from \"./store.js\";\n\n/**\n * The control plane: one signed grant per job, or a reason there is none.\n *\n * byollm_016 Amendment J and L. This is the open engine behind a relay's\n * `authorGrant` seam. It reads policy from a {@link PolicyStore} it does not\n * own and signs with a {@link GrantSigner} whose key it never sees, so the\n * two things byollm.cloud keeps — the data and the key — sit outside it, and\n * the rule over them is readable by anybody.\n *\n * ## One routes, one authorises, only one signs\n *\n * A relay already filters what it offers a device, by consent and by\n * membership. **That filter is an optimisation and this is the authority.**\n * Everything is checked again here, because the relay's projection can be\n * stale and because a grant asserting \"consented, member, admitted\" must be\n * true when it is signed rather than when something upstream last looked. If\n * the two disagree, this one wins and refuses.\n */\nexport class ControlPlane {\n  readonly #store: PolicyStore;\n  readonly #signer: GrantSigner;\n  readonly #now: () => number;\n  readonly #newId: () => string;\n\n  constructor(options: {\n    readonly store: PolicyStore;\n    readonly signer: GrantSigner;\n    /** Injectable clock, so tests move time instead of sleeping. */\n    readonly now?: () => number;\n    /** Injectable id source, so a test can assert what was signed. */\n    readonly newGrantId?: () => string;\n  }) {\n    this.#store = options.store;\n    this.#signer = options.signer;\n    this.#now = options.now ?? Date.now;\n    this.#newId = options.newGrantId ?? (() => `grant_${randomUUID()}`);\n  }\n\n  /** The key devices pin at pairing, from the same object that signs. */\n  get publicKey(): string {\n    return this.#signer.publicKey;\n  }\n\n  /**\n   * Author a grant for one claimed job, or decline with a reason.\n   *\n   * The order below is the law, and it is ordered by *whose* fact each step\n   * is: the device's own owner first, then the person's consent, then their\n   * membership, then their mapping, then this machine's ability to honour it.\n   * A step that fails stops the rest, so the reason returned names the first\n   * thing that was actually wrong rather than whichever check ran last.\n   */\n  async authorGrant(input: {\n    readonly job: ClaimedStub;\n    /** The site's id in this control plane's namespace, not its key id. */\n    readonly siteId: string;\n    /** The device owner asking. */\n    readonly owner: string;\n    /**\n     * Which of the site's declared purposes this job serves.\n     *\n     * Supplied by the caller rather than read off the job, because in the\n     * release that built this engine the stub does not carry one yet — every\n     * job is the site's {@link RESERVED_PURPOSE}. When purposes reach the\n     * wire, the caller passes the job's own and nothing here changes.\n     */\n    readonly purpose?: string;\n    /**\n     * What this device advertised it can serve.\n     *\n     * The control plane resolves a mapping to a service **from what the\n     * device said**, never from a name it invented. A mapping naming\n     * something this device does not offer is not honoured here — see\n     * `resolved-elsewhere`.\n     */\n    readonly capabilities: CapabilityMatrix;\n  }): Promise<GrantOutcome> {\n    const { job, owner } = input;\n    const purpose = input.purpose ?? RESERVED_PURPOSE;\n\n    let snapshot;\n    try {\n      snapshot = await this.#store.read({\n        siteId: input.siteId,\n        user: job.owner,\n        owner,\n      });\n    } catch {\n      /**\n       * A store that could not answer is not a refusal.\n       *\n       * Failing closed is right — nothing is signed — but the *shape* of the\n       * failure matters more than it looks. A permanent refusal here would\n       * mean a database blip permanently unpicked a job from a device, and\n       * nothing would ever put it back. Transient, therefore, and the job\n       * goes back in the queue.\n       */\n      return decline(\"store-unavailable\");\n    }\n\n    if (!snapshot.consented) return decline(\"not-consented\");\n\n    /**\n     * A device always runs its own owner's work, and no store is asked.\n     *\n     * Not an optimisation. Routing this through the store would put a law\n     * somewhere an implementation could get wrong — including by answering\n     * `member: false` for somebody's own account and silently stopping their\n     * own device. There is no answer a store could give that should change\n     * this, so it is not asked the question.\n     */\n    if (job.owner !== owner && !snapshot.member) return decline(\"not-a-member\");\n\n    const mapped = snapshot.mappings.find(\n      (mapping) => mapping.purpose === purpose && mapping.kind === job.kind,\n    );\n    /**\n     * An unmapped slot makes a purpose unavailable, never a site broken.\n     *\n     * Transient, because the remedy is the user's and they may take it: a\n     * mapping authored a minute from now should let this job run, and a\n     * permanent refusal would have quietly excluded the one device it was\n     * about to point at.\n     */\n    if (!mapped) return decline(\"unmapped\");\n\n    /**\n     * The device has to actually offer it, for this kind.\n     *\n     * Two different situations arrive here and this vantage cannot tell them\n     * apart: the mapping resolved to a *different* device of this owner's, or\n     * its referent is gone entirely — a service renamed or deleted. From one\n     * device's capabilities both look identical, so the name says only what\n     * is knowable here.\n     *\n     * Whether it is *no* device is a question for a sweep across the owner's\n     * services, which is where the \"your mapping needs updating\" notification\n     * belongs — not on the claim path, which sees one machine at a time.\n     */\n    /**\n     * Whose machine, before which service.\n     *\n     * A service id means something only inside its owner's namespace, so a\n     * mapping naming a teammate's `qwen` must not be satisfied by a different\n     * teammate's `qwen` — or by the mapper's own. Checked before the\n     * capability list, because a device that merely shares a name is not\n     * \"the wrong service\" but the wrong machine, and the capabilities of the\n     * wrong machine say nothing either way.\n     */\n    if ((mapped.owner ?? job.owner) !== owner) {\n      return decline(\"resolved-elsewhere\");\n    }\n\n    const offered = input.capabilities.some(\n      (capability) =>\n        capability.kind === job.kind && capability.service === mapped.service,\n    );\n    if (!offered) return decline(\"resolved-elsewhere\");\n\n    return {\n      granted: await this.#signer.sign({\n        grantId: this.#newId(),\n        jobId: job.id,\n        siteId: input.siteId,\n        user: job.owner,\n        owner,\n        purpose,\n        kind: job.kind,\n        service: mapped.service,\n        issuedAt: this.#now(),\n      }),\n    };\n  }\n}\n\n/**\n * Why no grant was authored — and, load-bearing, whether that is forever.\n *\n * The distinction exists because a relay releases a declined job, and a\n * release can carry `refused`, which means *never offer this job to this\n * device again*. Getting that wrong in the permissive direction is a\n * claim-refuse loop; getting it wrong in the strict direction is a job that\n * can never reach the machine it was always meant for, and no error anywhere.\n */\nexport type DeclineReason =\n  /** This person may not use this owner's devices. */\n  | \"not-a-member\"\n  /** This person has not authorised this site. */\n  | \"not-consented\"\n  /** They authorised it and left this slot empty. */\n  | \"unmapped\"\n  /** Their mapping names a service this device does not offer. */\n  | \"resolved-elsewhere\"\n  /** The policy store could not answer. Says nothing about the job. */\n  | \"store-unavailable\";\n\nexport interface Decline {\n  readonly reason: DeclineReason;\n  /**\n   * Never offer this job to this device again.\n   *\n   * True only for the two facts that a queued job cannot outlive: a person\n   * removed from a team, and consent withdrawn. Hole 1 ruled that removal\n   * stops future claims *including queued ones*, and this is where that is\n   * enforced.\n   *\n   * Everything else is a state the user can change, or a fault of ours. A\n   * permanent mark on those would outlive the condition that caused it.\n   */\n  readonly permanent: boolean;\n}\n\nexport type GrantOutcome =\n  | { readonly granted: SignedGrant; readonly declined?: undefined }\n  | { readonly granted?: undefined; readonly declined: Decline };\n\nconst PERMANENT: ReadonlySet<DeclineReason> = new Set([\n  \"not-a-member\",\n  \"not-consented\",\n]);\n\nfunction decline(reason: DeclineReason): GrantOutcome {\n  return { declined: { reason, permanent: PERMANENT.has(reason) } };\n}\n","import type { Mapping, PolicySnapshot, PolicyStore } from \"./store.js\";\n\n/**\n * A policy store in a `Map`, for tests and for a single-process self-hoster.\n *\n * It is the reference implementation in the sense that matters: the contract\n * suite runs against it, so it is the thing anybody else's store is compared\n * to. It is not a suggestion about how to build one — a real store is a\n * database, and this one forgets everything when the process ends.\n */\nexport class MemoryPolicyStore implements PolicyStore {\n  /** (siteId, user) to what that person authorised for that site. */\n  readonly #consents = new Map<string, Mapping[]>();\n  /** (siteId, user) pairs whose owner has paused them. */\n  readonly #paused = new Set<string>();\n  /** owner to the people who may use their devices. */\n  readonly #members = new Map<string, Set<string>>();\n\n  /**\n   * Record a consent, with the mapping it carries.\n   *\n   * One call because they are one act: the mapping **is** the consent\n   * (Amendment L), and a store that let them be written separately would\n   * allow a state — consented, no mappings, no way to have got there — that\n   * the product cannot produce.\n   *\n   * Consenting with an empty list is the real signup state, though: a person\n   * whose slots all had two candidates and who has not chosen yet.\n   */\n  consent(input: {\n    siteId: string;\n    user: string;\n    mappings?: readonly Mapping[];\n  }): void {\n    this.#consents.set(key(input.siteId, input.user), [\n      ...(input.mappings ?? []),\n    ]);\n    this.#paused.delete(key(input.siteId, input.user));\n  }\n\n  /**\n   * Pause a consent without withdrawing it.\n   *\n   * A real product state and not the same as revoking: the mapping survives,\n   * so resuming does not ask somebody to author their choices again. What it\n   * must not do is let work through — a relay's projection can lag by\n   * seconds, and a grant authored in that window would run work whose owner\n   * had just stopped it.\n   */\n  pause(input: { siteId: string; user: string }): void {\n    this.#paused.add(key(input.siteId, input.user));\n  }\n\n  /** Let it move again. */\n  resume(input: { siteId: string; user: string }): void {\n    this.#paused.delete(key(input.siteId, input.user));\n  }\n\n  /**\n   * Withdraw consent, which deletes the mapping with it.\n   *\n   * Not two operations. \"Revoking consent deletes the mapping — the mapping\n   * is the consent, so un-consenting unmaps\" (hole 2), and a store that could\n   * leave one behind would leave a resolution pointing at a service the\n   * person no longer authorises anybody to reach.\n   */\n  revoke(input: { siteId: string; user: string }): void {\n    this.#consents.delete(key(input.siteId, input.user));\n    this.#paused.delete(key(input.siteId, input.user));\n  }\n\n  /** Add somebody to an owner's team. */\n  addMember(input: { owner: string; user: string }): void {\n    const members = this.#members.get(input.owner) ?? new Set<string>();\n    members.add(input.user);\n    this.#members.set(input.owner, members);\n  }\n\n  /**\n   * Remove somebody from an owner's team.\n   *\n   * There is no \"blocked but still a member\": a team **is** access to its\n   * owner's devices and nothing else, so member-but-blocked is not a deferred\n   * feature, it is an empty state (Amendment J).\n   */\n  removeMember(input: { owner: string; user: string }): void {\n    this.#members.get(input.owner)?.delete(input.user);\n  }\n\n  read(input: {\n    siteId: string;\n    user: string;\n    owner: string;\n  }): Promise<PolicySnapshot> {\n    const id = key(input.siteId, input.user);\n    const mappings = this.#consents.get(id);\n    return Promise.resolve({\n      consented: mappings !== undefined && !this.#paused.has(id),\n      member: this.#members.get(input.owner)?.has(input.user) ?? false,\n      mappings: mappings ?? [],\n    });\n  }\n}\n\n/**\n * NUL-joined, for the reason `routeKey` is.\n *\n * A composite key is a parser waiting to meet an id containing its separator.\n * NUL cannot appear in either half, so no arrangement of a site id and a user\n * id can spell a different pair.\n */\nconst key = (siteId: string, user: string): string => `${siteId}\\u0000${user}`;\n","import {\n  signGrant,\n  type GrantClaims,\n  type SignedGrant,\n  type StoredKeys,\n} from \"@byollm/protocol\";\n\n/**\n * Whatever holds the key that grants are signed with.\n *\n * A function rather than a key, so custody never enters this package. A\n * self-hoster hands over a keypair; a hosted deployment can put the private\n * half behind a KMS and pass a signer that calls it, and the engine cannot\n * tell the difference — which is the point. Custody of the signing key is one\n * of the two things byollm.cloud keeps, and an engine that had to be given\n * the key could not be run any other way.\n *\n * `publicKey` sits on the same object deliberately. It is the value a relay\n * hands a device at pairing, and it is the value that must verify what\n * `sign` produces. Two separate configuration items would be two things a\n * deployment could set inconsistently — and the failure mode is a fleet that\n * refuses every job while every process reports itself healthy.\n */\nexport interface GrantSigner {\n  /** The public half, for a relay to hand devices at pairing. */\n  readonly publicKey: string;\n  sign(claims: GrantClaims): Promise<SignedGrant> | SignedGrant;\n}\n\n/**\n * Sign with a keypair this process holds.\n *\n * The implementation a self-hoster wants, and the one the tests use. A hosted\n * deployment writes its own against whatever holds its key.\n */\nexport function keypairSigner(\n  keys: Pick<StoredKeys, \"identityPrivate\" | \"identityPublic\">,\n): GrantSigner {\n  return {\n    publicKey: keys.identityPublic,\n    sign: (claims) => signGrant(keys, claims),\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/engine.ts","../src/memory.ts","../src/signer.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n  RESERVED_PURPOSE,\n  type CapabilityMatrix,\n  type ClaimedStub,\n  type SignedGrant,\n} from \"@byollm/protocol\";\nimport type { GrantSigner } from \"./signer.js\";\nimport type { PolicyStore } from \"./store.js\";\n\n/**\n * The control plane: one signed grant per job, or a reason there is none.\n *\n * byollm_016 Amendment J and L. This is the open engine behind a relay's\n * `authorGrant` seam. It reads policy from a {@link PolicyStore} it does not\n * own and signs with a {@link GrantSigner} whose key it never sees, so the\n * two things byollm.cloud keeps — the data and the key — sit outside it, and\n * the rule over them is readable by anybody.\n *\n * ## One routes, one authorises, only one signs\n *\n * A relay already filters what it offers a device, by consent and by\n * membership. **That filter is an optimisation and this is the authority.**\n * Everything is checked again here, because the relay's projection can be\n * stale and because a grant asserting \"consented, member, admitted\" must be\n * true when it is signed rather than when something upstream last looked. If\n * the two disagree, this one wins and refuses.\n */\nexport class ControlPlane {\n  readonly #store: PolicyStore;\n  readonly #signer: GrantSigner;\n  readonly #now: () => number;\n  readonly #newId: () => string;\n\n  constructor(options: {\n    readonly store: PolicyStore;\n    readonly signer: GrantSigner;\n    /** Injectable clock, so tests move time instead of sleeping. */\n    readonly now?: () => number;\n    /** Injectable id source, so a test can assert what was signed. */\n    readonly newGrantId?: () => string;\n  }) {\n    this.#store = options.store;\n    this.#signer = options.signer;\n    this.#now = options.now ?? Date.now;\n    this.#newId = options.newGrantId ?? (() => `grant_${randomUUID()}`);\n  }\n\n  /** The key devices pin at pairing, from the same object that signs. */\n  get publicKey(): string {\n    return this.#signer.publicKey;\n  }\n\n  /**\n   * Author a grant for one claimed job, or decline with a reason.\n   *\n   * The order below is the law, and it is ordered by *whose* fact each step\n   * is: the device's own owner first, then the person's consent, then their\n   * membership, then their mapping, then this machine's ability to honour it.\n   * A step that fails stops the rest, so the reason returned names the first\n   * thing that was actually wrong rather than whichever check ran last.\n   */\n  async authorGrant(input: {\n    readonly job: ClaimedStub;\n    /** The site's id in this control plane's namespace, for the policy read. */\n    readonly siteId: string;\n    /**\n     * The same site, as the key id the device pinned — the value that gets\n     * signed.\n     *\n     * Two ids for one site, and both are needed: the store is keyed by the\n     * control plane's own id, and the device knows sites only by what it\n     * pinned. The grant carries the one the device can check without asking\n     * anybody, which is the whole point of a signed document.\n     */\n    readonly siteKey: string;\n    /** The device owner asking. */\n    readonly owner: string;\n    /**\n     * Which of the site's declared purposes this job serves.\n     *\n     * Supplied by the caller rather than read off the job, because in the\n     * release that built this engine the stub does not carry one yet — every\n     * job is the site's {@link RESERVED_PURPOSE}. When purposes reach the\n     * wire, the caller passes the job's own and nothing here changes.\n     */\n    readonly purpose?: string;\n    /**\n     * What this device advertised it can serve.\n     *\n     * The control plane resolves a mapping to a service **from what the\n     * device said**, never from a name it invented. A mapping naming\n     * something this device does not offer is not honoured here — see\n     * `resolved-elsewhere`.\n     */\n    readonly capabilities: CapabilityMatrix;\n  }): Promise<GrantOutcome> {\n    const { job, owner } = input;\n    const purpose = input.purpose ?? RESERVED_PURPOSE;\n\n    let snapshot;\n    try {\n      snapshot = await this.#store.read({\n        // The control plane's own id: the store is keyed by it, and the key\n        // id below is for the device. Two ids, two readers, neither\n        // substitutable for the other.\n        siteId: input.siteId,\n        user: job.owner,\n        owner,\n      });\n    } catch {\n      /**\n       * A store that could not answer is not a refusal.\n       *\n       * Failing closed is right — nothing is signed — but the *shape* of the\n       * failure matters more than it looks. A permanent refusal here would\n       * mean a database blip permanently unpicked a job from a device, and\n       * nothing would ever put it back. Transient, therefore, and the job\n       * goes back in the queue.\n       */\n      return decline(\"store-unavailable\");\n    }\n\n    if (!snapshot.consented) return decline(\"not-consented\");\n\n    /**\n     * A device always runs its own owner's work, and no store is asked.\n     *\n     * Not an optimisation. Routing this through the store would put a law\n     * somewhere an implementation could get wrong — including by answering\n     * `member: false` for somebody's own account and silently stopping their\n     * own device. There is no answer a store could give that should change\n     * this, so it is not asked the question.\n     */\n    if (job.owner !== owner && !snapshot.member) return decline(\"not-a-member\");\n\n    const mapped = snapshot.mappings.find(\n      (mapping) => mapping.purpose === purpose && mapping.kind === job.kind,\n    );\n    /**\n     * An unmapped slot makes a purpose unavailable, never a site broken.\n     *\n     * Transient, because the remedy is the user's and they may take it: a\n     * mapping authored a minute from now should let this job run, and a\n     * permanent refusal would have quietly excluded the one device it was\n     * about to point at.\n     */\n    if (!mapped) return decline(\"unmapped\");\n\n    /**\n     * The device has to actually offer it, for this kind.\n     *\n     * Two different situations arrive here and this vantage cannot tell them\n     * apart: the mapping resolved to a *different* device of this owner's, or\n     * its referent is gone entirely — a service renamed or deleted. From one\n     * device's capabilities both look identical, so the name says only what\n     * is knowable here.\n     *\n     * Whether it is *no* device is a question for a sweep across the owner's\n     * services, which is where the \"your mapping needs updating\" notification\n     * belongs — not on the claim path, which sees one machine at a time.\n     */\n    /**\n     * Whose machine, before which service.\n     *\n     * A service id means something only inside its owner's namespace, so a\n     * mapping naming a teammate's `qwen` must not be satisfied by a different\n     * teammate's `qwen` — or by the mapper's own. Checked before the\n     * capability list, because a device that merely shares a name is not\n     * \"the wrong service\" but the wrong machine, and the capabilities of the\n     * wrong machine say nothing either way.\n     */\n    if ((mapped.owner ?? job.owner) !== owner) {\n      return decline(\"resolved-elsewhere\");\n    }\n\n    const offered = input.capabilities.some(\n      (capability) =>\n        capability.kind === job.kind && capability.service === mapped.service,\n    );\n    if (!offered) return decline(\"resolved-elsewhere\");\n\n    return {\n      granted: await this.#signer.sign({\n        grantId: this.#newId(),\n        jobId: job.id,\n        site: input.siteKey,\n        user: job.owner,\n        owner,\n        purpose,\n        kind: job.kind,\n        service: mapped.service,\n        issuedAt: this.#now(),\n      }),\n    };\n  }\n}\n\n/**\n * Why no grant was authored — and, load-bearing, whether that is forever.\n *\n * The distinction exists because a relay releases a declined job, and a\n * release can carry `refused`, which means *never offer this job to this\n * device again*. Getting that wrong in the permissive direction is a\n * claim-refuse loop; getting it wrong in the strict direction is a job that\n * can never reach the machine it was always meant for, and no error anywhere.\n */\nexport type DeclineReason =\n  /** This person may not use this owner's devices. */\n  | \"not-a-member\"\n  /** This person has not authorised this site. */\n  | \"not-consented\"\n  /** They authorised it and left this slot empty. */\n  | \"unmapped\"\n  /** Their mapping names a service this device does not offer. */\n  | \"resolved-elsewhere\"\n  /** The policy store could not answer. Says nothing about the job. */\n  | \"store-unavailable\";\n\nexport interface Decline {\n  readonly reason: DeclineReason;\n  /**\n   * Never offer this job to this device again.\n   *\n   * True only for the two facts that a queued job cannot outlive: a person\n   * removed from a team, and consent withdrawn. Hole 1 ruled that removal\n   * stops future claims *including queued ones*, and this is where that is\n   * enforced.\n   *\n   * Everything else is a state the user can change, or a fault of ours. A\n   * permanent mark on those would outlive the condition that caused it.\n   */\n  readonly permanent: boolean;\n}\n\nexport type GrantOutcome =\n  | { readonly granted: SignedGrant; readonly declined?: undefined }\n  | { readonly granted?: undefined; readonly declined: Decline };\n\nconst PERMANENT: ReadonlySet<DeclineReason> = new Set([\n  \"not-a-member\",\n  \"not-consented\",\n]);\n\nfunction decline(reason: DeclineReason): GrantOutcome {\n  return { declined: { reason, permanent: PERMANENT.has(reason) } };\n}\n","import type { Mapping, PolicySnapshot, PolicyStore } from \"./store.js\";\n\n/**\n * A policy store in a `Map`, for tests and for a single-process self-hoster.\n *\n * It is the reference implementation in the sense that matters: the contract\n * suite runs against it, so it is the thing anybody else's store is compared\n * to. It is not a suggestion about how to build one — a real store is a\n * database, and this one forgets everything when the process ends.\n */\nexport class MemoryPolicyStore implements PolicyStore {\n  /** (siteId, user) to what that person authorised for that site. */\n  readonly #consents = new Map<string, Mapping[]>();\n  /** (siteId, user) pairs whose owner has paused them. */\n  readonly #paused = new Set<string>();\n  /** owner to the people who may use their devices. */\n  readonly #members = new Map<string, Set<string>>();\n\n  /**\n   * Record a consent, with the mapping it carries.\n   *\n   * One call because they are one act: the mapping **is** the consent\n   * (Amendment L), and a store that let them be written separately would\n   * allow a state — consented, no mappings, no way to have got there — that\n   * the product cannot produce.\n   *\n   * Consenting with an empty list is the real signup state, though: a person\n   * whose slots all had two candidates and who has not chosen yet.\n   */\n  consent(input: {\n    siteId: string;\n    user: string;\n    mappings?: readonly Mapping[];\n  }): void {\n    this.#consents.set(key(input.siteId, input.user), [\n      ...(input.mappings ?? []),\n    ]);\n    this.#paused.delete(key(input.siteId, input.user));\n  }\n\n  /**\n   * Pause a consent without withdrawing it.\n   *\n   * A real product state and not the same as revoking: the mapping survives,\n   * so resuming does not ask somebody to author their choices again. What it\n   * must not do is let work through — a relay's projection can lag by\n   * seconds, and a grant authored in that window would run work whose owner\n   * had just stopped it.\n   */\n  pause(input: { siteId: string; user: string }): void {\n    this.#paused.add(key(input.siteId, input.user));\n  }\n\n  /** Let it move again. */\n  resume(input: { siteId: string; user: string }): void {\n    this.#paused.delete(key(input.siteId, input.user));\n  }\n\n  /**\n   * Withdraw consent, which deletes the mapping with it.\n   *\n   * Not two operations. \"Revoking consent deletes the mapping — the mapping\n   * is the consent, so un-consenting unmaps\" (hole 2), and a store that could\n   * leave one behind would leave a resolution pointing at a service the\n   * person no longer authorises anybody to reach.\n   */\n  revoke(input: { siteId: string; user: string }): void {\n    this.#consents.delete(key(input.siteId, input.user));\n    this.#paused.delete(key(input.siteId, input.user));\n  }\n\n  /** Add somebody to an owner's team. */\n  addMember(input: { owner: string; user: string }): void {\n    const members = this.#members.get(input.owner) ?? new Set<string>();\n    members.add(input.user);\n    this.#members.set(input.owner, members);\n  }\n\n  /**\n   * Remove somebody from an owner's team.\n   *\n   * There is no \"blocked but still a member\": a team **is** access to its\n   * owner's devices and nothing else, so member-but-blocked is not a deferred\n   * feature, it is an empty state (Amendment J).\n   */\n  removeMember(input: { owner: string; user: string }): void {\n    this.#members.get(input.owner)?.delete(input.user);\n  }\n\n  read(input: {\n    siteId: string;\n    user: string;\n    owner: string;\n  }): Promise<PolicySnapshot> {\n    const id = key(input.siteId, input.user);\n    const mappings = this.#consents.get(id);\n    return Promise.resolve({\n      consented: mappings !== undefined && !this.#paused.has(id),\n      member: this.#members.get(input.owner)?.has(input.user) ?? false,\n      mappings: mappings ?? [],\n    });\n  }\n}\n\n/**\n * NUL-joined, for the reason `routeKey` is.\n *\n * A composite key is a parser waiting to meet an id containing its separator.\n * NUL cannot appear in either half, so no arrangement of a site id and a user\n * id can spell a different pair.\n */\nconst key = (siteId: string, user: string): string => `${siteId}\\u0000${user}`;\n","import {\n  signGrant,\n  type GrantClaims,\n  type SignedGrant,\n  type StoredKeys,\n} from \"@byollm/protocol\";\n\n/**\n * Whatever holds the key that grants are signed with.\n *\n * A function rather than a key, so custody never enters this package. A\n * self-hoster hands over a keypair; a hosted deployment can put the private\n * half behind a KMS and pass a signer that calls it, and the engine cannot\n * tell the difference — which is the point. Custody of the signing key is one\n * of the two things byollm.cloud keeps, and an engine that had to be given\n * the key could not be run any other way.\n *\n * `publicKey` sits on the same object deliberately. It is the value a relay\n * hands a device at pairing, and it is the value that must verify what\n * `sign` produces. Two separate configuration items would be two things a\n * deployment could set inconsistently — and the failure mode is a fleet that\n * refuses every job while every process reports itself healthy.\n */\nexport interface GrantSigner {\n  /** The public half, for a relay to hand devices at pairing. */\n  readonly publicKey: string;\n  sign(claims: GrantClaims): Promise<SignedGrant> | SignedGrant;\n}\n\n/**\n * Sign with a keypair this process holds.\n *\n * The implementation a self-hoster wants, and the one the tests use. A hosted\n * deployment writes its own against whatever holds its key.\n */\nexport function keypairSigner(\n  keys: Pick<StoredKeys, \"identityPrivate\" | \"identityPublic\">,\n): GrantSigner {\n  return {\n    publicKey: keys.identityPublic,\n    sign: (claims) => signGrant(keys, claims),\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byollm/control-plane",
-  "version": "0.1.0-alpha.58",
+  "version": "0.1.0-alpha.59",
   "type": "module",
   "description": "The reference control plane: resolves a user's mapping and authors one signed grant per job, against a policy store it does not own.",
   "license": "MIT",
@@ -30,7 +30,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@byollm/protocol": "0.1.0-alpha.58"
+    "@byollm/protocol": "0.1.0-alpha.59"
   },
   "publishConfig": {
     "access": "public"