@substrat-run/contracts 0.88.0 → 0.90.0

package/dist/idempotency.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Request idempotency on the operation surface (#116).
+ *
+ * A client whose request times out does not know whether the work happened. It
+ * retries, and a second work order exists. This is the vocabulary that lets the
+ * retry return the FIRST response instead of doing the work twice.
+ *
+ * ## This is not the event spine's idempotency
+ *
+ * Consumers have been required-idempotent since the beginning and the contract
+ * suite checks it: a consumer may see an event more than once and must settle to
+ * the same state. That is about the spine re-delivering. This is about a CLIENT
+ * re-sending — a different boundary, a different actor, and no relationship
+ * between the two beyond the word.
+ *
+ * ## Why the wire half lives here and the rest does not
+ *
+ * The same split `concurrency.ts` makes one file over: contracts sits below the
+ * spine, so it can say what the header is called, what makes a key well-formed
+ * and what makes two requests the same request. It must not know which table
+ * remembers the answer. `@substrat-run/kernel`'s `idempotency.ts` owns that, and
+ * the adapters own where it runs.
+ *
+ * ## The property that makes this cheap
+ *
+ * Invokes are serialised per scope in both adapters (`rt.actor.enqueue`, the
+ * ScopeDO's queue), so a duplicate cannot overlap the original — by the time the
+ * retry takes its turn, the first request has committed or rolled back. Every
+ * other implementation of this feature needs an in-flight state and a 409 for
+ * "still running"; this one does not, and the reason is a property of the host
+ * rather than an accident worth relying on quietly.
+ */
+/** The request header carrying the client's retry token. */
+export declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * Set on a response the server did not compute — it replayed a recorded one.
+ *
+ * Advisory, and worth having anyway: without it a retry is indistinguishable
+ * from a first request that happened to succeed, which makes "did my key work?"
+ * unanswerable from the client side and turns every integration test of a retry
+ * path into a database query.
+ */
+export declare const IDEMPOTENCY_REPLAYED_HEADER = "Idempotency-Replayed";
+/**
+ * The header a cross-origin browser client cannot read unless the server says it
+ * may — the same trap `PAGE_EXPOSED_HEADERS` and `CONCURRENCY_EXPOSED_HEADERS`
+ * document, and the mildest of the three: an unexposed `Idempotency-Replayed`
+ * costs a client an observation, never a guarantee. The dedupe still happened.
+ */
+export declare const IDEMPOTENCY_EXPOSED_HEADERS: readonly ["Idempotency-Replayed"];
+/**
+ * How long a key is remembered: 24 hours.
+ *
+ * Long enough to cover the retries anything sane performs — an agent's backoff,
+ * a queue's redelivery, a person reloading a page that failed — and short enough
+ * that the recorded responses are a cache rather than an archive.
+ *
+ * The window is not only a storage bound, and the other reason is the one worth
+ * writing down: a recorded response is a SECOND COPY of whatever the operation
+ * returned, sitting in the scope database outside the erasure path that reaches
+ * the outbox (a shred nulls `payload` and keeps the row; it does not know about
+ * this table). A copy that expires in a day is defensible. One that expires in a
+ * quarter is a disclosure nobody declared, and one that never expires is a second
+ * database of personal data with no owner.
+ */
+export declare const IDEMPOTENCY_RETENTION_MS: number;
+/**
+ * The largest result that is recorded for replay: 128 KiB of JSON.
+ *
+ * Above it the key is still recorded — with no body — and a replay is REFUSED
+ * rather than re-executed. That is the fail-closed direction: refusing a retry
+ * costs a caller an error it can act on, while re-running the operation is the
+ * duplicate this feature exists to prevent, arrived at through the feature
+ * itself. Writes return entity-shaped results and do not approach this; a list
+ * read might, and a list read never carries a key (the mount forwards the header
+ * on unsafe methods only).
+ */
+export declare const IDEMPOTENCY_RESULT_LIMIT: number;
+/** Longest key accepted, matching the IETF draft's guidance for the header. */
+export declare const IDEMPOTENCY_KEY_MAX_LENGTH = 255;
+/**
+ * Is this a key we will store and compare?
+ *
+ * Visible ASCII, bounded, non-empty. Deliberately permissive about STRUCTURE — a
+ * UUID is the convention and this refuses to require one, because a client whose
+ * natural key is an order number should not have to hash it into a shape we
+ * prefer. What it refuses is a key that would make the table a place to put
+ * things: control characters, whitespace, and anything unbounded.
+ *
+ * The key is never interpreted. It is compared, and it is scoped to the subject
+ * that sent it, so one client's choice of key cannot collide with another's.
+ */
+export declare function isValidIdempotencyKey(key: string): boolean;
+/**
+ * Deterministic JSON — the same value serialises to the same string, whatever
+ * order its keys arrived in.
+ *
+ * `JSON.stringify` preserves insertion order, so `{a:1,b:2}` and `{b:2,a:1}`
+ * produce different text for the same request. A fingerprint built on that would
+ * call a retry a different request roughly whenever a client rebuilt its body
+ * from a map — which is to say, unpredictably, and in production rather than in
+ * a test.
+ *
+ * Arrays keep their order, because in a request body order IS meaning (the
+ * second line item is not the first). Only object keys are sorted.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * What makes two requests the same request: the operation and its PARSED input.
+ *
+ * **Parsed, not raw**, and that is load-bearing. The host parses every invocation
+ * against the operation's declared schema before anything else runs, which
+ * applies defaults — so a retry that omits an optional field the original sent
+ * explicitly at its default value is the same request, and fingerprinting the raw
+ * body would call it a different one and refuse the retry with a 409.
+ *
+ * The operation name is inside the hash rather than beside it in the key, so a
+ * client reusing one key for two different operations is a MISMATCH (409) rather
+ * than two independent records. A key is a client's assertion that "this is the
+ * same request I sent before"; two operations is the clearest possible case of
+ * that assertion being false, and silently honouring it would replay one
+ * operation's response for another one's call.
+ *
+ * SHA-256 via Web Crypto — the same API in Node, Workers and browsers, per the
+ * repo's standing rule against node-only imports and against hand-rolled hashes.
+ */
+export declare function requestFingerprint(operation: string, input: unknown): Promise<string>;
+/**
+ * The `conflict` reason slugs this feature owns.
+ *
+ * Slugs rather than codes, per the closed taxonomy: a module never invents a
+ * code, it narrows an existing one with a reason it owns. Both are `conflict`
+ * (409) because both mean the same thing to a client — *the key you sent is not
+ * available for this request* — and differ only in why, which is what the slug
+ * carries.
+ */
+export declare const IDEMPOTENCY_REUSED = "idempotency_key_reused";
+export declare const IDEMPOTENCY_REPLAY_UNAVAILABLE = "idempotency_replay_unavailable";
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,oBAAoB,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,yBAAyB,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,mCAAyC,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,QAAsB,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAEnD,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWpD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAI3F;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAC3D,eAAO,MAAM,8BAA8B,mCAAmC,CAAC"}

package/dist/idempotency.js

@@ -0,0 +1,161 @@
+/**
+ * Request idempotency on the operation surface (#116).
+ *
+ * A client whose request times out does not know whether the work happened. It
+ * retries, and a second work order exists. This is the vocabulary that lets the
+ * retry return the FIRST response instead of doing the work twice.
+ *
+ * ## This is not the event spine's idempotency
+ *
+ * Consumers have been required-idempotent since the beginning and the contract
+ * suite checks it: a consumer may see an event more than once and must settle to
+ * the same state. That is about the spine re-delivering. This is about a CLIENT
+ * re-sending — a different boundary, a different actor, and no relationship
+ * between the two beyond the word.
+ *
+ * ## Why the wire half lives here and the rest does not
+ *
+ * The same split `concurrency.ts` makes one file over: contracts sits below the
+ * spine, so it can say what the header is called, what makes a key well-formed
+ * and what makes two requests the same request. It must not know which table
+ * remembers the answer. `@substrat-run/kernel`'s `idempotency.ts` owns that, and
+ * the adapters own where it runs.
+ *
+ * ## The property that makes this cheap
+ *
+ * Invokes are serialised per scope in both adapters (`rt.actor.enqueue`, the
+ * ScopeDO's queue), so a duplicate cannot overlap the original — by the time the
+ * retry takes its turn, the first request has committed or rolled back. Every
+ * other implementation of this feature needs an in-flight state and a 409 for
+ * "still running"; this one does not, and the reason is a property of the host
+ * rather than an accident worth relying on quietly.
+ */
+/** The request header carrying the client's retry token. */
+export const IDEMPOTENCY_KEY_HEADER = 'Idempotency-Key';
+/**
+ * Set on a response the server did not compute — it replayed a recorded one.
+ *
+ * Advisory, and worth having anyway: without it a retry is indistinguishable
+ * from a first request that happened to succeed, which makes "did my key work?"
+ * unanswerable from the client side and turns every integration test of a retry
+ * path into a database query.
+ */
+export const IDEMPOTENCY_REPLAYED_HEADER = 'Idempotency-Replayed';
+/**
+ * The header a cross-origin browser client cannot read unless the server says it
+ * may — the same trap `PAGE_EXPOSED_HEADERS` and `CONCURRENCY_EXPOSED_HEADERS`
+ * document, and the mildest of the three: an unexposed `Idempotency-Replayed`
+ * costs a client an observation, never a guarantee. The dedupe still happened.
+ */
+export const IDEMPOTENCY_EXPOSED_HEADERS = [IDEMPOTENCY_REPLAYED_HEADER];
+/**
+ * How long a key is remembered: 24 hours.
+ *
+ * Long enough to cover the retries anything sane performs — an agent's backoff,
+ * a queue's redelivery, a person reloading a page that failed — and short enough
+ * that the recorded responses are a cache rather than an archive.
+ *
+ * The window is not only a storage bound, and the other reason is the one worth
+ * writing down: a recorded response is a SECOND COPY of whatever the operation
+ * returned, sitting in the scope database outside the erasure path that reaches
+ * the outbox (a shred nulls `payload` and keeps the row; it does not know about
+ * this table). A copy that expires in a day is defensible. One that expires in a
+ * quarter is a disclosure nobody declared, and one that never expires is a second
+ * database of personal data with no owner.
+ */
+export const IDEMPOTENCY_RETENTION_MS = 24 * 60 * 60 * 1000;
+/**
+ * The largest result that is recorded for replay: 128 KiB of JSON.
+ *
+ * Above it the key is still recorded — with no body — and a replay is REFUSED
+ * rather than re-executed. That is the fail-closed direction: refusing a retry
+ * costs a caller an error it can act on, while re-running the operation is the
+ * duplicate this feature exists to prevent, arrived at through the feature
+ * itself. Writes return entity-shaped results and do not approach this; a list
+ * read might, and a list read never carries a key (the mount forwards the header
+ * on unsafe methods only).
+ */
+export const IDEMPOTENCY_RESULT_LIMIT = 128 * 1024;
+/** Longest key accepted, matching the IETF draft's guidance for the header. */
+export const IDEMPOTENCY_KEY_MAX_LENGTH = 255;
+/**
+ * Is this a key we will store and compare?
+ *
+ * Visible ASCII, bounded, non-empty. Deliberately permissive about STRUCTURE — a
+ * UUID is the convention and this refuses to require one, because a client whose
+ * natural key is an order number should not have to hash it into a shape we
+ * prefer. What it refuses is a key that would make the table a place to put
+ * things: control characters, whitespace, and anything unbounded.
+ *
+ * The key is never interpreted. It is compared, and it is scoped to the subject
+ * that sent it, so one client's choice of key cannot collide with another's.
+ */
+export function isValidIdempotencyKey(key) {
+    if (key.length === 0 || key.length > IDEMPOTENCY_KEY_MAX_LENGTH)
+        return false;
+    return /^[\x21-\x7e]+$/.test(key);
+}
+/**
+ * Deterministic JSON — the same value serialises to the same string, whatever
+ * order its keys arrived in.
+ *
+ * `JSON.stringify` preserves insertion order, so `{a:1,b:2}` and `{b:2,a:1}`
+ * produce different text for the same request. A fingerprint built on that would
+ * call a retry a different request roughly whenever a client rebuilt its body
+ * from a map — which is to say, unpredictably, and in production rather than in
+ * a test.
+ *
+ * Arrays keep their order, because in a request body order IS meaning (the
+ * second line item is not the first). Only object keys are sorted.
+ */
+export function canonicalJson(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((entry) => canonicalJson(entry)).join(',')}]`;
+    const entries = Object.entries(value)
+        // `undefined` is absent, not a value — `JSON.stringify` drops such a property
+        // and so must this, or an optional field explicitly passed as `undefined`
+        // would fingerprint differently from the same field simply omitted.
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}
+/**
+ * What makes two requests the same request: the operation and its PARSED input.
+ *
+ * **Parsed, not raw**, and that is load-bearing. The host parses every invocation
+ * against the operation's declared schema before anything else runs, which
+ * applies defaults — so a retry that omits an optional field the original sent
+ * explicitly at its default value is the same request, and fingerprinting the raw
+ * body would call it a different one and refuse the retry with a 409.
+ *
+ * The operation name is inside the hash rather than beside it in the key, so a
+ * client reusing one key for two different operations is a MISMATCH (409) rather
+ * than two independent records. A key is a client's assertion that "this is the
+ * same request I sent before"; two operations is the clearest possible case of
+ * that assertion being false, and silently honouring it would replay one
+ * operation's response for another one's call.
+ *
+ * SHA-256 via Web Crypto — the same API in Node, Workers and browsers, per the
+ * repo's standing rule against node-only imports and against hand-rolled hashes.
+ */
+export async function requestFingerprint(operation, input) {
+    const bytes = new TextEncoder().encode(canonicalJson([operation, input ?? null]));
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * The `conflict` reason slugs this feature owns.
+ *
+ * Slugs rather than codes, per the closed taxonomy: a module never invents a
+ * code, it narrows an existing one with a reason it owns. Both are `conflict`
+ * (409) because both mean the same thing to a client — *the key you sent is not
+ * available for this request* — and differ only in why, which is what the slug
+ * carries.
+ */
+export const IDEMPOTENCY_REUSED = 'idempotency_key_reused';
+export const IDEMPOTENCY_REPLAY_UNAVAILABLE = 'idempotency_replay_unavailable';
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/impersonation.d.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+/**
+ * Acting as a principal with the REAL actor preserved (K-42, #868).
+ *
+ * Supporting a customer's live vertical means seeing what a named person sees.
+ * Every platform grows that surface eventually, and the version that grows by
+ * itself is a session swap: the staff member becomes the user, and the trail
+ * says the user did it. That is the version an audit fails.
+ *
+ * So an impersonated operation carries **two** actors. The permission model
+ * answers as the impersonated principal — that is the whole point, and an
+ * intersection with the staff actor's own authority would be empty, because a
+ * platform actor is not a principal in any tenant and holds no scope permissions
+ * at all (`PlatformActorId` is branded apart from `PrincipalId` for exactly that
+ * reason). What bounds the session instead is its MODE, its clock and its
+ * reason: `read-only` unless someone wrote down why not, expiring on its own,
+ * and admin-logged before it can be used.
+ *
+ * Every record the scope writes about who did what keeps both: the outbox
+ * envelope, the denial log, the platform-intent journal. Stamped kernel-side on
+ * K-34's pattern — `impersonation` is absent from `DomainEventInput`, so module
+ * code can neither claim a session it is not in nor drop the one it is.
+ */
+/**
+ * The hard ceiling on a session's life, in minutes.
+ *
+ * A support session is bounded because the alternative is a credential: a
+ * session with no end is a second way to be that person, held by whoever last
+ * opened one. K-33's rewind is time-boxed and audited on the same argument, and
+ * the number is deliberately short enough that renewing is the normal case —
+ * each renewal being a fresh admin-log row is the feature, not the friction.
+ */
+export declare const IMPERSONATION_MAX_MINUTES = 60;
+/** What a caller gets by not saying — a quarter hour, well inside the ceiling. */
+export declare const IMPERSONATION_DEFAULT_MINUTES = 15;
+/**
+ * The floor on a reason, in characters.
+ *
+ * Not a validation nicety: the reason is the only field of this record a human
+ * writes, and 'x' passing means the field is decoration. Short enough that a
+ * ticket reference ('#4182 — invoice missing') clears it.
+ */
+export declare const IMPERSONATION_MIN_REASON = 8;
+/** ULID, minted platform-side. Brands apart from every other id in the tree. */
+export declare const impersonationSessionId: z.core.$ZodBranded<z.ZodString, "ImpersonationSessionId", "out">;
+export type ImpersonationSessionId = z.infer<typeof impersonationSessionId>;
+/**
+ * What the session may do, and the answer to #868's last open question.
+ *
+ * `read-only` is most of the debugging value at a fraction of the argument, so
+ * it is the default and it is MECHANICAL: a read-only invocation's transaction
+ * is rolled back rather than committed, and the effecting verbs (`emit`,
+ * `requestPlatform`, `grant`, `revoke`, `link`) refuse outright, so a support
+ * engineer cannot approve an invoice by accident and a vertical cannot arrange
+ * for them to. `write` exists because "reproduce the failing save" is a real
+ * support task — it just has to be asked for, in a session that says so.
+ */
+export declare const impersonationMode: z.ZodEnum<{
+    "read-only": "read-only";
+    write: "write";
+}>;
+export type ImpersonationMode = z.infer<typeof impersonationMode>;
+/**
+ * What staff supply to open a session. The acting actor is NOT here: it is the
+ * `PlatformActorId` every `HostAdmin` verb already takes, so it can no more be
+ * chosen by the caller than the actor on an admin-log row can.
+ */
+export declare const beginImpersonationInput: z.ZodObject<{
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    scopeId: z.core.$ZodBranded<z.ZodString, "ScopeId", "out">;
+    principal: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    reason: z.ZodString;
+    minutes: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        "read-only": "read-only";
+        write: "write";
+    }>>;
+}, z.core.$strip>;
+export type BeginImpersonationInput = z.infer<typeof beginImpersonationInput>;
+/**
+ * A session as the directory holds it, and as `listImpersonations` reads it back.
+ *
+ * `endedAt` is the explicit close. It is distinct from expiry: a session that
+ * ran out is over because time passed, one that was ended is over because
+ * somebody stopped it, and an incident review wants to be able to tell those
+ * apart. Neither is a delete — this record is evidence (K-21's tombstone rule).
+ */
+export declare const impersonationSession: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "ImpersonationSessionId", "out">;
+    actor: z.core.$ZodBranded<z.ZodString, "PlatformActorId", "out">;
+    principal: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    scopeId: z.core.$ZodBranded<z.ZodString, "ScopeId", "out">;
+    reason: z.ZodString;
+    mode: z.ZodEnum<{
+        "read-only": "read-only";
+        write: "write";
+    }>;
+    startedAt: z.core.$ZodBranded<z.ZodString, "Instant", "out">;
+    expiresAt: z.core.$ZodBranded<z.ZodString, "Instant", "out">;
+    endedAt: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "Instant", "out">>;
+}, z.core.$strip>;
+export type ImpersonationSession = z.infer<typeof impersonationSession>;
+/**
+ * The two actors a record keeps — the stamp the kernel puts on an event
+ * envelope, a denial row and a platform intent raised under a session.
+ *
+ * `by` rather than `actor`, because the envelope's `actor` field is already
+ * taken and already correct: the impersonated principal is who the permission
+ * model answered about and who the domain fact is about. This says who was
+ * holding the keyboard, which is a different question with a different answer.
+ */
+export declare const impersonationStamp: z.ZodObject<{
+    session: z.core.$ZodBranded<z.ZodString, "ImpersonationSessionId", "out">;
+    by: z.core.$ZodBranded<z.ZodString, "PlatformActorId", "out">;
+}, z.core.$strip>;
+export type ImpersonationStamp = z.infer<typeof impersonationStamp>;
+/**
+ * How a caller narrows a read of the session log. `active` is evaluated against
+ * the reader's clock — a session neither ended nor expired — because "who is in
+ * a customer's data right now" is the question an incident opens with.
+ */
+export declare const impersonationFilter: z.ZodObject<{
+    tenantId: z.ZodOptional<z.ZodString>;
+    scopeId: z.ZodOptional<z.ZodString>;
+    actor: z.ZodOptional<z.ZodString>;
+    principal: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ImpersonationFilter = z.infer<typeof impersonationFilter>;
+/** How many sessions an unbounded read returns — a screenful, newest first. */
+export declare const DEFAULT_IMPERSONATION_LIMIT = 50;
+//# sourceMappingURL=impersonation.d.ts.map

package/dist/impersonation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impersonation.d.ts","sourceRoot":"","sources":["../src/impersonation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,kEAAsD,CAAC;AAC1F,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;EAAiC,CAAC;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAUlC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;iBAa/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;;;iBAG7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEtE,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,KAAK,CAAC"}

package/dist/impersonation.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { instant, platformActorId, principalId, scopeId, tenantId } from './ids.js';
+/**
+ * Acting as a principal with the REAL actor preserved (K-42, #868).
+ *
+ * Supporting a customer's live vertical means seeing what a named person sees.
+ * Every platform grows that surface eventually, and the version that grows by
+ * itself is a session swap: the staff member becomes the user, and the trail
+ * says the user did it. That is the version an audit fails.
+ *
+ * So an impersonated operation carries **two** actors. The permission model
+ * answers as the impersonated principal — that is the whole point, and an
+ * intersection with the staff actor's own authority would be empty, because a
+ * platform actor is not a principal in any tenant and holds no scope permissions
+ * at all (`PlatformActorId` is branded apart from `PrincipalId` for exactly that
+ * reason). What bounds the session instead is its MODE, its clock and its
+ * reason: `read-only` unless someone wrote down why not, expiring on its own,
+ * and admin-logged before it can be used.
+ *
+ * Every record the scope writes about who did what keeps both: the outbox
+ * envelope, the denial log, the platform-intent journal. Stamped kernel-side on
+ * K-34's pattern — `impersonation` is absent from `DomainEventInput`, so module
+ * code can neither claim a session it is not in nor drop the one it is.
+ */
+/**
+ * The hard ceiling on a session's life, in minutes.
+ *
+ * A support session is bounded because the alternative is a credential: a
+ * session with no end is a second way to be that person, held by whoever last
+ * opened one. K-33's rewind is time-boxed and audited on the same argument, and
+ * the number is deliberately short enough that renewing is the normal case —
+ * each renewal being a fresh admin-log row is the feature, not the friction.
+ */
+export const IMPERSONATION_MAX_MINUTES = 60;
+/** What a caller gets by not saying — a quarter hour, well inside the ceiling. */
+export const IMPERSONATION_DEFAULT_MINUTES = 15;
+/**
+ * The floor on a reason, in characters.
+ *
+ * Not a validation nicety: the reason is the only field of this record a human
+ * writes, and 'x' passing means the field is decoration. Short enough that a
+ * ticket reference ('#4182 — invoice missing') clears it.
+ */
+export const IMPERSONATION_MIN_REASON = 8;
+/** ULID, minted platform-side. Brands apart from every other id in the tree. */
+export const impersonationSessionId = z.string().min(1).brand();
+/**
+ * What the session may do, and the answer to #868's last open question.
+ *
+ * `read-only` is most of the debugging value at a fraction of the argument, so
+ * it is the default and it is MECHANICAL: a read-only invocation's transaction
+ * is rolled back rather than committed, and the effecting verbs (`emit`,
+ * `requestPlatform`, `grant`, `revoke`, `link`) refuse outright, so a support
+ * engineer cannot approve an invoice by accident and a vertical cannot arrange
+ * for them to. `write` exists because "reproduce the failing save" is a real
+ * support task — it just has to be asked for, in a session that says so.
+ */
+export const impersonationMode = z.enum(['read-only', 'write']);
+/**
+ * What staff supply to open a session. The acting actor is NOT here: it is the
+ * `PlatformActorId` every `HostAdmin` verb already takes, so it can no more be
+ * chosen by the caller than the actor on an admin-log row can.
+ */
+export const beginImpersonationInput = z.object({
+    tenantId,
+    scopeId,
+    /** WHO to act as. A principal of this tenant; nothing here mints one. */
+    principal: principalId,
+    /** Why. Recorded on the session and in the admin log, and never optional. */
+    reason: z.string().min(IMPERSONATION_MIN_REASON),
+    /** Capped at `IMPERSONATION_MAX_MINUTES`; a longer ask is refused, not clamped. */
+    minutes: z.number().int().positive().max(IMPERSONATION_MAX_MINUTES).optional(),
+    mode: impersonationMode.optional(),
+});
+/**
+ * A session as the directory holds it, and as `listImpersonations` reads it back.
+ *
+ * `endedAt` is the explicit close. It is distinct from expiry: a session that
+ * ran out is over because time passed, one that was ended is over because
+ * somebody stopped it, and an incident review wants to be able to tell those
+ * apart. Neither is a delete — this record is evidence (K-21's tombstone rule).
+ */
+export const impersonationSession = z.object({
+    id: impersonationSessionId,
+    /** The REAL actor: the staff member who opened the session. */
+    actor: platformActorId,
+    /** The principal being acted as — who the permission model answers about. */
+    principal: principalId,
+    tenantId,
+    scopeId,
+    reason: z.string().min(IMPERSONATION_MIN_REASON),
+    mode: impersonationMode,
+    startedAt: instant,
+    expiresAt: instant,
+    endedAt: instant.nullable(),
+});
+/**
+ * The two actors a record keeps — the stamp the kernel puts on an event
+ * envelope, a denial row and a platform intent raised under a session.
+ *
+ * `by` rather than `actor`, because the envelope's `actor` field is already
+ * taken and already correct: the impersonated principal is who the permission
+ * model answered about and who the domain fact is about. This says who was
+ * holding the keyboard, which is a different question with a different answer.
+ */
+export const impersonationStamp = z.object({
+    session: impersonationSessionId,
+    by: platformActorId,
+});
+/**
+ * How a caller narrows a read of the session log. `active` is evaluated against
+ * the reader's clock — a session neither ended nor expired — because "who is in
+ * a customer's data right now" is the question an incident opens with.
+ */
+export const impersonationFilter = z.object({
+    tenantId: z.string().min(1).optional(),
+    scopeId: z.string().min(1).optional(),
+    actor: z.string().min(1).optional(),
+    principal: z.string().min(1).optional(),
+    active: z.boolean().optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+});
+/** How many sessions an unbounded read returns — a screenful, newest first. */
+export const DEFAULT_IMPERSONATION_LIMIT = 50;
+//# sourceMappingURL=impersonation.js.map

package/dist/impersonation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"impersonation.js","sourceRoot":"","sources":["../src/impersonation.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -24,9 +24,11 @@ export * from './tenancy.js';
 export * from './introspection.js';
 export * from './pagination.js';
 export * from './concurrency.js';
+export * from './idempotency.js';
 export * from './connections.js';
 export * from './control-plane.js';
 export * from './permission.js';
+export * from './impersonation.js';
 export * from './events.js';
 export * from './errors.js';
 export * from './platform-request.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -24,9 +24,11 @@ export * from './tenancy.js';
 export * from './introspection.js';
 export * from './pagination.js';
 export * from './concurrency.js';
+export * from './idempotency.js';
 export * from './connections.js';
 export * from './control-plane.js';
 export * from './permission.js';
+export * from './impersonation.js';
 export * from './events.js';
 export * from './errors.js';
 export * from './platform-request.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}

package/dist/openapi.d.ts

@@ -62,6 +62,16 @@ export interface ApiOperationDoc {
         over: string;
         idFrom: string;
     };
+    /**
+     * `false` when the operation declared out of request idempotency (#116).
+     *
+     * Present only as a refusal, matching the declaration: every other unsafe
+     * operation honours `Idempotency-Key`, so the header is documented on all of
+     * them and this is what removes it from the one that would refuse it. A header
+     * documented where it is refused is worse than one documented nowhere — a
+     * client reads it and builds a retry it does not have.
+     */
+    idempotency?: false;
     paged?: {
         /** Present on a handler-composed read: the ENTRY field the cursor walks. */
         sortKey?: string;

package/dist/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E;;;;OAIG;IACH;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,KAAK,CAAC,EAAE;QACN,4EAA4E;QAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB;;;;WAIG;QACH,IAAI,CAAC,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;YAC5B,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;SAChC,CAAC;KACH,CAAC;CACH;AAgBD,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,UAAU,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqOzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAM,GAC3E,UAAU,CAiCZ"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7E;;;;OAIG;IACH;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,KAAK,CAAC,EAAE;QACN,4EAA4E;QAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB;;;;WAIG;QACH,IAAI,CAAC,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;YAC5B,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;SAChC,CAAC;KACH,CAAC;CACH;AAgBD,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,UAAU,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsPzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAM,GAC3E,UAAU,CAoCZ"}