Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

10.0 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// bento/id — the document's side of the identity agent contract.
//
// A document is a file, and a file cannot keep a secret, so it cannot hold a
// person's keys. The agent can: bento/home (the extension, the iOS, Android and
// desktop apps) keeps the account and device keys and acts for the person when
// a document asks. This module is the ONE definition of what a document may ask
// and what it gets back. Each host implements it over its own channel
// (home/bridge.js on the native hosts, the extension's served page), and the
// document only ever talks to the object below.
//
// Three rules shape the contract:
//   - PRIVATE KEYS NEVER CROSS. Every call returns a result: a public identity,
//     a signature, a public binding. The only secret that ever comes back is a
//     document key the person was given (`unwrap`, phase 2).
//   - THE HOST KNOWS WHO IS ASKING. No call takes a docId or a caller name: the
//     host identifies the calling document from what the platform reports (the
//     file path, the opened URL), never from the page, and exposes this object
//     only to a verified, signed Bento shell (gate 1).
//   - NO HOST, NO CHANGE. `identityAgent()` returns null wherever there is no
//     agent — a bare file:// tab, an older host, a doctored file — and every
//     caller then does exactly what it did before identity existed.

/** The contract version a host's agent object must carry. Members marked
 *  optional are additions within this version; a breaking change bumps it, and
 *  a document then sees no agent rather than one it would misread. */
export const IDENTITY_CONTRACT = 1

/** The global the host defines, before the runtime boots, on a verified shell. */
export const IDENTITY_GLOBAL = '__bentoIdentity'

/** Who is using this document, as vouched for. Public fields only. */
export interface PublicIdentity {
  /** display name, as the binding states it */
  name: string
  /** the verified address, exactly as bound (lower-case) */
  email: string
  /** who vouched: 'id.bento.page', an organisation's domain, or a vault id */
  vouchedBy: string
  /** the person's account public key: raw P-256 point, base64url */
  accountPub: string
  /** this device's key, the one `sign` uses: raw P-256 point, base64url */
  devicePub: string
}

/**
 * What a signature is for. The agent signs only a payload whose shape matches
 * the purpose, so a prompt shown for one kind of action can never yield a
 * signature on another. The payloads are the existing dot-joined statements
 * (docs/collab-design.md):
 *   frame    — `${i}.${d}`, an op batch or snapshot (routine)
 *   prove    — `prove.${nonce}.${room}`, the per-socket possession proof (routine)
 *   delegate — `dlg.${devicePub}`, an invite key admitting a device (routine)
 *   show     — `live`/`end` and `${kind}.aud.${i}`, presenting controls (routine)
 *   invite   — `inv.${pub}.${role}.${exp}`, an owner granting a role (high authority)
 *   revoke   — `rev.${pub}`, an owner removing a key (high authority)
 * Routine purposes are signed with the DEVICE key and ride the session (§2e).
 * The high-authority ones are signed with the room's OWNER key, which the relay
 * verifies. In phase 1 that key still lives in the document file and the kernel
 * signs with it directly, exactly as today: no agent holds an owner key, so a
 * phase-1 agent refuses `invite`/`revoke` ('unavailable'). The agent holds an
 * owner key only once a document converts to identity mode (phase 2). Then it
 * signs `inv.`/`rev.` after its own consent prompt, and the CONSENT key signs a
 * separate `cns.` (statements.ts) that travels beside it. A cns. needs the
 * verifier's audience and challenge, so phase 2 adds a call that carries them;
 * this contract version has none. The shared payload matcher is statements.ts.
 */
export type SignPurpose = 'frame' | 'prove' | 'delegate' | 'show' | 'invite' | 'revoke'

/** Why a signature was not given. */
export type SignRefusal =
  /** the person said no at the host's prompt */
  | 'declined'
  /** past the idle or overall timeout: refused until the person re-authenticates (§2e B) */
  | 'reauth'
  /** the payload does not match the purpose */
  | 'purpose'
  /** no identity is set up on this device */
  | 'no-identity'
  /** the agent cannot sign right now (locked, busy, no key store) */
  | 'unavailable'

export type SignResult =
  /** `sig` is raw r‖s (64 bytes) base64url, low-S normalised — never DER;
   *  `pub` is the key that signed */
  | { ok: true; sig: string; pub: string }
  | { ok: false; reason: SignRefusal }

/** Look up a person by a key already in the room, or (phase 2) by address. */
export type ResolveQuery = { pub: string } | { email: string }

/** A public binding the agent found and checked. */
export interface ResolvedIdentity {
  name: string
  email: string
  vouchedBy: string
  accountPub: string
  /** when this agent first saw this binding (epoch ms) — trust on first use */
  firstSeen: number
  /** true if the binding differs from the one this agent saw before */
  changed: boolean
}

/** Roles a person can be given in a document (phase 2). */
export type ShareRole = 'reader' | 'editor' | 'owner'

export interface IdentityAgent {
  readonly contract: number
  /** The person using this document, or null when no identity is set up or
   *  they declined to use it here (consent is per document). */
  whoami(): Promise<PublicIdentity | null>
  /** Sign `payload` (the exact UTF-8 text) for `purpose` with this device's key.
   *  A host method that throws reaches the caller as a REJECTED promise: callers
   *  treat a rejection exactly like `{ ok: false, reason: 'unavailable' }` and
   *  never let it escape. Check the payload first with statements.ts
   *  payloadMatchesPurpose; the host refuses a mismatch either way. */
  sign(purpose: SignPurpose, payload: string): Promise<SignResult>
  /** Who a key in the room (or, phase 2, an address) belongs to; null if unknown.
   *  A lookup by `{email}` is consent-gated and rate-limited by the HOST, so a
   *  document cannot use it to probe which addresses have an identity. */
  resolve(query: ResolveQuery): Promise<ResolvedIdentity | null>
  /** PHASE 2: open the document key wrapped to this person (`collab.wraps`).
   *  Returns the raw key, or null when no wrap here is theirs. */
  unwrap?(wrap: { to: string; kw: string }): Promise<Uint8Array | null>
  /** PHASE 2: share this document with a person, after the host's own consent. */
  share?(email: string, role: ShareRole): Promise<{ ok: true } | { ok: false; reason: string }>
}

let held: IdentityAgent | undefined

/**
 * The host's identity agent for this page, or null when there is none — in
 * which case the caller does what it always did.
 *
 * WHAT A HOST MUST DEFINE, or the document sees no agent:
 *   - the global as a DATA property that is non-writable and non-configurable
 *     (`Object.defineProperty(globalThis, '__bentoIdentity', { value, writable:
 *     false, configurable: false })`) — never a getter, which could answer
 *     differently on each read;
 *   - the agent object itself FROZEN;
 *   - its methods as CLOSURES that do not use `this`. They are called with
 *     `this` undefined, so a method that reaches its transport through `this`
 *     (or through anything page code could rewrite later) fails here instead of
 *     being redirectable after capture. Capture the transport at definition time.
 *
 * A valid agent is captured once; later changes cannot redirect a call. An
 * absent or malformed one is not cached, so an agent the host defines a moment
 * late is still found on a later call.
 */
export function identityAgent(): IdentityAgent | null {
  if (held) return held
  const agent = detect(globalThis)
  if (agent) held = agent
  return agent
}

function detect(scope: object): IdentityAgent | null {
  let candidate: unknown
  try {
    const d = Object.getOwnPropertyDescriptor(scope, IDENTITY_GLOBAL)
    // a data property the page can neither overwrite nor redefine; no getters
    if (!d || !('value' in d) || d.writable !== false || d.configurable !== false) return null
    candidate = d.value
  } catch { return null }
  return capture(candidate)
}

/** detect() against a stand-in global, without caching. For the rig only: a
 *  non-configurable property on the real globalThis could never be reset. */
export function detectIdentityAgentForTest(scope: object): IdentityAgent | null {
  return detect(scope)
}

function capture(c: unknown): IdentityAgent | null {
  try {
    if (!c || typeof c !== 'object') return null
    // a frozen host object: no member can be swapped after this check
    if (!Object.isFrozen(c)) return null
    const o = c as Record<string, unknown>
    if (o.contract !== IDENTITY_CONTRACT) return null
    const fn = (k: string) => (typeof o[k] === 'function' ? (o[k] as (...a: unknown[]) => unknown) : null)
    const whoami = fn('whoami'), sign = fn('sign'), resolve = fn('resolve')
    if (!whoami || !sign || !resolve) return null
    // phase-2 members are optional, but if present they must be callable
    for (const k of ['unwrap', 'share']) if (o[k] !== undefined && !fn(k)) return null
    const unwrap = fn('unwrap'), share = fn('share')
    // `this` undefined: a host method gets nothing a page could later rewrite
    const call = <F>(f: (...a: unknown[]) => unknown) =>
      ((...args: unknown[]) => Reflect.apply(f, undefined, args)) as unknown as F
    return Object.freeze({
      contract: IDENTITY_CONTRACT,
      whoami: call<IdentityAgent['whoami']>(whoami),
      sign: call<IdentityAgent['sign']>(sign),
      resolve: call<IdentityAgent['resolve']>(resolve),
      ...(unwrap ? { unwrap: call<NonNullable<IdentityAgent['unwrap']>>(unwrap) } : {}),
      ...(share ? { share: call<NonNullable<IdentityAgent['share']>>(share) } : {}),
    })
  } catch {
    // a hostile getter, a revoked proxy: no agent, never a throw into the caller
    return null
  }
}

/** Forget the captured agent. For rigs that toggle the host between cases. */
export function resetIdentityAgentForTest(): void {
  held = undefined
}