better-call 0.0.0-experimental.01ff4b77

package/dist/capability.d.cts

@@ -0,0 +1,189 @@
+import { TypeDefination } from "./schema.cjs";
+import { OnEntry } from "./module.cjs";
+import { FnDefination } from "./fn.cjs";
+import { VarDefination } from "./var.cjs";
+//#region src/capability.d.ts
+type Keypair = {
+  id: string;
+  sign: (payload: string) => Promise<string>;
+};
+declare const generateKeypair: () => Promise<Keypair>;
+/** The name of a right: a fn key, optionally pinned to exact input
+ * fields. Never signed on its own - delegations carry caps, invocations
+ * spend them. */
+type Cap = string | {
+  fn: string;
+  input?: Record<string, unknown>;
+};
+declare const fnOf: (cap: Cap) => string;
+declare const fmtCap: (cap: Cap) => string;
+/** Does holding `parent` justify holding `child`? Same fn, and every
+ * field the parent pins must be pinned identically by the child. */
+declare const covers: (parent: Cap, child: Cap) => boolean;
+/** Do these held caps authorize calling `fn` with `input`? */
+declare const permits: (caps: Cap[], fn: string, input: unknown) => boolean;
+type Delegation = {
+  typ: "dlg";
+  iss: string;
+  aud: string;
+  sub: string;
+  caps: Cap[];
+  exp: number;
+  prf?: Delegation;
+  sig: string;
+};
+type Invocation = {
+  typ: "inv";
+  iss: string;
+  call: string;
+  input?: unknown;
+  exp: number;
+  nonce: string;
+  prf: Delegation;
+  sig: string;
+};
+declare const mintDelegation: (issuer: Keypair, body: Omit<Delegation, "typ" | "iss" | "sig">) => Promise<Delegation>;
+declare const mintInvocation: (holder: Keypair, call: string, proof: Delegation, input?: unknown) => Promise<Invocation>;
+declare class CapabilityError extends Error {
+  constructor(message: string);
+}
+/** A crafted chain of self-signed links (valid until the root check at the
+ * very bottom) would otherwise force unbounded recursion and signature
+ * verifications - a cheap denial-of-service. Cap the depth. */
+declare const MAX_DELEGATION_DEPTH = 16;
+/** Walk the chain: every link signed, attenuating, unexpired, rooted. */
+declare const verifyDelegation: (root: string, link: Delegation, depth?: number) => Promise<Delegation>;
+declare const verifyInvocation: (root: string, token: Invocation) => Promise<{
+  subject: string;
+  caps: Cap[];
+  holder: string;
+}>;
+type Attestation = {
+  typ: "idt";
+  iss: string;
+  sub: string;
+  exp: number;
+  sig: string;
+};
+declare const verifyAttestation: (root: string, token: Attestation) => Promise<string>;
+declare const capability: VarDefination<"capability", {
+  subject: string;
+  caps: Cap[];
+  holder: string;
+  entry: string | null;
+} | null, undefined, never>;
+declare const validateCaller: (fnKey: string) => OnEntry<string, unknown>;
+type Challenge = {
+  id: string;
+  subject: string;
+  holder: string;
+  caps: Cap[];
+  goal?: string;
+  status: "pending" | "approved" | "denied";
+};
+/**
+ * Authority never checks a call - `validateCaller` owns that. It answers
+ * the questions that come BEFORE any call: what references does a caller
+ * start with, what proves WHO a caller acts for, and how are requests
+ * for more settled?
+ */
+type Authority = {
+  /**
+   * The first grant: what a request with no caps named pays out, given
+   * who was proven - and `null` IS an answer. Nobody's defaults should
+   * be just enough to go earn attestation (here: sign in); there is no
+   * separate "bootstrap caps" list.
+   */
+  defaults: (subject: string | null) => Cap[];
+  /**
+   * Reads a proven subject out of ANY fn's result: the moment authority
+   * learns WHO, attested proof rides back alongside the result.
+   */
+  identify: (result: unknown) => string | null;
+  /**
+   * Turns a subject into the portable attestation handed back. Defaults
+   * to a token this server signs itself; swap together with `verify` to
+   * lean on an external IDP instead.
+   */
+  attest?: (subject: string) => unknown | Promise<unknown>;
+  /** Decides whether a presented attestation passes. */
+  verify?: (attestation: unknown) => string | null | Promise<string | null>;
+  /** How widening requests are settled. Default: challenge everything. */
+  decide?: (request: {
+    subject: string;
+    caps: Cap[];
+    goal?: string;
+  }) => "approve" | "challenge" | "deny";
+  /** Delegation and attestation lifetime, seconds. */
+  ttl?: number;
+};
+/**
+ * The remote boundary - the ONLY place a reference is ever reified or
+ * verified, and the only construction in the whole model. Capabilities
+ * are not registered or created anywhere: the fns you serve ARE the
+ * capability space, one per key, and EVERY one of them validates its
+ * caller - there is no public list. Everything crosses as data: a fn
+ * key, JSON input, and a freshly minted invocation. Verification sets
+ * `c.capability`; `validateCaller` on every fn does the rest.
+ */
+declare const serve: (modules: Record<string, unknown>, authority: Authority) => Promise<{
+  exec: FnDefination<{
+    readonly call: string;
+    readonly input: unknown;
+    readonly token: unknown;
+  }, Promise<unknown>, "capability.exec", {
+    readonly call: TypeDefination<string, string, never>;
+    readonly input: TypeDefination<unknown, unknown, never>;
+    readonly token: TypeDefination<unknown, unknown, never>;
+  }, readonly [], {}, {
+    capability?: ({
+      subject: string;
+      caps: (string | {
+        fn: string;
+        input?: {
+          [x: string]: unknown;
+        } | undefined;
+      })[];
+      holder: string;
+      entry: string | null;
+    } & {
+      subject: string;
+      caps: Cap[];
+      holder: string;
+      entry: string | null;
+    }) | null | undefined;
+  }, unknown>;
+  decide: (id: string, approve: boolean) => Challenge | undefined;
+  challenges: Map<string, Challenge>;
+  key: string;
+}>;
+type Transport = (message: {
+  call: string;
+  input?: unknown;
+  token?: Invocation;
+}) => Promise<any>;
+/**
+ * An agent: a keypair plus whatever reified references it holds. Born
+ * asking - creation requests the default caps. Without attestation, the
+ * answer is the bootstrap challenge: a delegation whose only power is
+ * signing in. With attestation (passed in, or earned by a call whose
+ * result attests), the answer is the defaults. EVERY call re-mints a
+ * single-use invocation over the fn AND the input; nothing is public.
+ */
+declare const createAgent: (transport: Transport, options?: {
+  attestation?: unknown;
+}) => Promise<{
+  id: string;
+  attestation: () => unknown;
+  hold: (delegation: Delegation) => void;
+  held: () => Delegation | null;
+  call: (call: string, input?: unknown) => Promise<any>;
+  request: (caps: Cap[], goal?: string) => Promise<any>;
+  /** Hand a SLICE of held references to another agent, re-minted for
+   * their key - fewer fns, or the same fn pinned to narrower input.
+   * The other agent spends with their own signature. */
+  delegate: (toAgentId: string, caps: Cap[]) => Promise<Delegation>;
+}>;
+//#endregion
+export { Attestation, Authority, Cap, CapabilityError, Challenge, Delegation, Invocation, Keypair, MAX_DELEGATION_DEPTH, Transport, capability, covers, createAgent, fmtCap, fnOf, generateKeypair, mintDelegation, mintInvocation, permits, serve, validateCaller, verifyAttestation, verifyDelegation, verifyInvocation };
+//# sourceMappingURL=capability.d.cts.map

package/dist/capability.d.mts

@@ -0,0 +1,189 @@
+import { TypeDefination } from "./schema.mjs";
+import { OnEntry } from "./module.mjs";
+import { FnDefination } from "./fn.mjs";
+import { VarDefination } from "./var.mjs";
+//#region src/capability.d.ts
+type Keypair = {
+  id: string;
+  sign: (payload: string) => Promise<string>;
+};
+declare const generateKeypair: () => Promise<Keypair>;
+/** The name of a right: a fn key, optionally pinned to exact input
+ * fields. Never signed on its own - delegations carry caps, invocations
+ * spend them. */
+type Cap = string | {
+  fn: string;
+  input?: Record<string, unknown>;
+};
+declare const fnOf: (cap: Cap) => string;
+declare const fmtCap: (cap: Cap) => string;
+/** Does holding `parent` justify holding `child`? Same fn, and every
+ * field the parent pins must be pinned identically by the child. */
+declare const covers: (parent: Cap, child: Cap) => boolean;
+/** Do these held caps authorize calling `fn` with `input`? */
+declare const permits: (caps: Cap[], fn: string, input: unknown) => boolean;
+type Delegation = {
+  typ: "dlg";
+  iss: string;
+  aud: string;
+  sub: string;
+  caps: Cap[];
+  exp: number;
+  prf?: Delegation;
+  sig: string;
+};
+type Invocation = {
+  typ: "inv";
+  iss: string;
+  call: string;
+  input?: unknown;
+  exp: number;
+  nonce: string;
+  prf: Delegation;
+  sig: string;
+};
+declare const mintDelegation: (issuer: Keypair, body: Omit<Delegation, "typ" | "iss" | "sig">) => Promise<Delegation>;
+declare const mintInvocation: (holder: Keypair, call: string, proof: Delegation, input?: unknown) => Promise<Invocation>;
+declare class CapabilityError extends Error {
+  constructor(message: string);
+}
+/** A crafted chain of self-signed links (valid until the root check at the
+ * very bottom) would otherwise force unbounded recursion and signature
+ * verifications - a cheap denial-of-service. Cap the depth. */
+declare const MAX_DELEGATION_DEPTH = 16;
+/** Walk the chain: every link signed, attenuating, unexpired, rooted. */
+declare const verifyDelegation: (root: string, link: Delegation, depth?: number) => Promise<Delegation>;
+declare const verifyInvocation: (root: string, token: Invocation) => Promise<{
+  subject: string;
+  caps: Cap[];
+  holder: string;
+}>;
+type Attestation = {
+  typ: "idt";
+  iss: string;
+  sub: string;
+  exp: number;
+  sig: string;
+};
+declare const verifyAttestation: (root: string, token: Attestation) => Promise<string>;
+declare const capability: VarDefination<"capability", {
+  subject: string;
+  caps: Cap[];
+  holder: string;
+  entry: string | null;
+} | null, undefined, never>;
+declare const validateCaller: (fnKey: string) => OnEntry<string, unknown>;
+type Challenge = {
+  id: string;
+  subject: string;
+  holder: string;
+  caps: Cap[];
+  goal?: string;
+  status: "pending" | "approved" | "denied";
+};
+/**
+ * Authority never checks a call - `validateCaller` owns that. It answers
+ * the questions that come BEFORE any call: what references does a caller
+ * start with, what proves WHO a caller acts for, and how are requests
+ * for more settled?
+ */
+type Authority = {
+  /**
+   * The first grant: what a request with no caps named pays out, given
+   * who was proven - and `null` IS an answer. Nobody's defaults should
+   * be just enough to go earn attestation (here: sign in); there is no
+   * separate "bootstrap caps" list.
+   */
+  defaults: (subject: string | null) => Cap[];
+  /**
+   * Reads a proven subject out of ANY fn's result: the moment authority
+   * learns WHO, attested proof rides back alongside the result.
+   */
+  identify: (result: unknown) => string | null;
+  /**
+   * Turns a subject into the portable attestation handed back. Defaults
+   * to a token this server signs itself; swap together with `verify` to
+   * lean on an external IDP instead.
+   */
+  attest?: (subject: string) => unknown | Promise<unknown>;
+  /** Decides whether a presented attestation passes. */
+  verify?: (attestation: unknown) => string | null | Promise<string | null>;
+  /** How widening requests are settled. Default: challenge everything. */
+  decide?: (request: {
+    subject: string;
+    caps: Cap[];
+    goal?: string;
+  }) => "approve" | "challenge" | "deny";
+  /** Delegation and attestation lifetime, seconds. */
+  ttl?: number;
+};
+/**
+ * The remote boundary - the ONLY place a reference is ever reified or
+ * verified, and the only construction in the whole model. Capabilities
+ * are not registered or created anywhere: the fns you serve ARE the
+ * capability space, one per key, and EVERY one of them validates its
+ * caller - there is no public list. Everything crosses as data: a fn
+ * key, JSON input, and a freshly minted invocation. Verification sets
+ * `c.capability`; `validateCaller` on every fn does the rest.
+ */
+declare const serve: (modules: Record<string, unknown>, authority: Authority) => Promise<{
+  exec: FnDefination<{
+    readonly call: string;
+    readonly input: unknown;
+    readonly token: unknown;
+  }, Promise<unknown>, "capability.exec", {
+    readonly call: TypeDefination<string, string, never>;
+    readonly input: TypeDefination<unknown, unknown, never>;
+    readonly token: TypeDefination<unknown, unknown, never>;
+  }, readonly [], {}, {
+    capability?: ({
+      subject: string;
+      caps: (string | {
+        fn: string;
+        input?: {
+          [x: string]: unknown;
+        } | undefined;
+      })[];
+      holder: string;
+      entry: string | null;
+    } & {
+      subject: string;
+      caps: Cap[];
+      holder: string;
+      entry: string | null;
+    }) | null | undefined;
+  }, unknown>;
+  decide: (id: string, approve: boolean) => Challenge | undefined;
+  challenges: Map<string, Challenge>;
+  key: string;
+}>;
+type Transport = (message: {
+  call: string;
+  input?: unknown;
+  token?: Invocation;
+}) => Promise<any>;
+/**
+ * An agent: a keypair plus whatever reified references it holds. Born
+ * asking - creation requests the default caps. Without attestation, the
+ * answer is the bootstrap challenge: a delegation whose only power is
+ * signing in. With attestation (passed in, or earned by a call whose
+ * result attests), the answer is the defaults. EVERY call re-mints a
+ * single-use invocation over the fn AND the input; nothing is public.
+ */
+declare const createAgent: (transport: Transport, options?: {
+  attestation?: unknown;
+}) => Promise<{
+  id: string;
+  attestation: () => unknown;
+  hold: (delegation: Delegation) => void;
+  held: () => Delegation | null;
+  call: (call: string, input?: unknown) => Promise<any>;
+  request: (caps: Cap[], goal?: string) => Promise<any>;
+  /** Hand a SLICE of held references to another agent, re-minted for
+   * their key - fewer fns, or the same fn pinned to narrower input.
+   * The other agent spends with their own signature. */
+  delegate: (toAgentId: string, caps: Cap[]) => Promise<Delegation>;
+}>;
+//#endregion
+export { Attestation, Authority, Cap, CapabilityError, Challenge, Delegation, Invocation, Keypair, MAX_DELEGATION_DEPTH, Transport, capability, covers, createAgent, fmtCap, fnOf, generateKeypair, mintDelegation, mintInvocation, permits, serve, validateCaller, verifyAttestation, verifyDelegation, verifyInvocation };
+//# sourceMappingURL=capability.d.mts.map