@xyo-network/event-kit-protocol 0.0.1

package/README.md

@@ -0,0 +1,33 @@
+# `@xyo-network/event-kit-protocol`
+
+Transport-neutral verification and admission orchestration for Event Kit
+wakes:
+
+1. Verify a real ES256K wallet JWT with the XYO SDK
+2. Bind JWT `eventHash` to the wake Payload data hash
+3. Bind the Payload to one immutable audience/deployment/queue/controller route
+4. Require a fresh, evidenced Statement Graph grant
+5. Resolve replay, logical idempotency, receipt creation, and durable enqueue
+   through one atomic inbox boundary
+
+The D-002 split now exists as pure `verifyWakeRequest` plus stateful
+`admitAndEnqueue` over explicit `WakeGrantAuthorizer` and `AtomicWakeInbox`
+ports. Protocol code owns no cloud or transport SDK. The stateful layer invokes
+injected I/O, while the inbox contract deliberately owns durable enqueue or a
+transactional outbox instead of exposing a split queue callback. See Yellow
+Paper §6 and §13.
+
+D-002's target is a raw strict XYO Payload plus a real short-lived wallet JWT;
+there is no separate event signature.
+
+`createMemoryWakeInbox` ships one conformant `AtomicWakeInbox`: it serializes
+the critical section, binds a fresh `jti` to an existing wake receipt, and hands
+the wake to its sink before consuming either identity, so a failing sink leaves
+the attempt retryable. It is single-process and loses state on restart — a
+durable adapter and full runtime qualification are still pending, so this is not
+production evidence.
+
+The pre-D-002 `admitWake` / `acceptWake` callback scaffold, its injected crypto
+port, the split `has`/`remember` replay store, and the `isPublisherEnabled`
+grant viewer have been removed. `verifyWakeRequest` + `admitAndEnqueue` over
+`WakeGrantAuthorizer` and `AtomicWakeInbox` are the only admission surface.

package/dist/neutral/admissionTypes.d.ts

@@ -0,0 +1,110 @@
+import type { DeploymentId, Hash, NormalizedAddress, WakeId, WakeJwtAudience, WakeJwtId } from '@xyo-network/event-kit-schemas';
+import type { AdmittedWake } from './types.ts';
+/** Replay records survive token expiry by this amount to cover receiver skew. */
+export declare const EVENT_KIT_REPLAY_RETENTION_SKEW_SECONDS = 60;
+export interface WakeGrantAuthorizationRequest {
+    readonly controller: NormalizedAddress;
+    readonly deploymentId: DeploymentId;
+    readonly expectedHead: number;
+    readonly publisher: NormalizedAddress;
+    readonly queueId?: string;
+}
+/** Concrete grant evidence required for every enabled decision. */
+export interface WakeGrantEvidence {
+    readonly assertedAtBlock: number;
+    readonly controller: NormalizedAddress;
+    readonly deploymentId: DeploymentId;
+    readonly id: string;
+    readonly queueId?: string;
+    readonly target: NormalizedAddress;
+}
+export interface WakeGrantAuthorizationDisabled {
+    readonly atBlock: number;
+    readonly enabled: false;
+    /** Optional diagnostics. The core rejects disagreement with its trusted input. */
+    readonly expectedHead?: number;
+    /** Optional diagnostics. The core recomputes lag instead of trusting this value. */
+    readonly lag?: number;
+}
+export interface WakeGrantAuthorizationEnabled {
+    readonly atBlock: number;
+    readonly enabled: true;
+    /** Optional diagnostics. The core rejects disagreement with its trusted input. */
+    readonly expectedHead?: number;
+    readonly grant: WakeGrantEvidence;
+    /** Optional diagnostics. The core recomputes lag instead of trusting this value. */
+    readonly lag?: number;
+}
+export type WakeGrantAuthorizationDecision = WakeGrantAuthorizationDisabled | WakeGrantAuthorizationEnabled;
+/**
+ * Stateful Statement Graph authorization port. Implementations must evaluate
+ * the exact controller, scope, publisher, and expected finalized head supplied
+ * for this request.
+ */
+export interface WakeGrantAuthorizer {
+    authorizePublisher: (request: WakeGrantAuthorizationRequest) => Promise<WakeGrantAuthorizationDecision>;
+}
+/** Normalized grant snapshot accepted by the protocol core. */
+export interface AuthorizedWakeGrant {
+    readonly atBlock: number;
+    readonly expectedHead: number;
+    readonly grant: WakeGrantEvidence;
+    readonly lag: number;
+}
+export interface WakeAdmissionAttempt {
+    readonly audience: WakeJwtAudience;
+    readonly eventHash: Hash;
+    readonly jwtId: WakeJwtId;
+    readonly publisher: NormalizedAddress;
+    /** Token replay record retention deadline (`exp + 60`). */
+    readonly retainJwtUntil: number;
+    readonly wakeId: WakeId;
+}
+/** Stable receipt bound to both durable admission indexes. */
+export interface WakeAdmissionReceipt {
+    readonly audience: WakeJwtAudience;
+    readonly eventHash: Hash;
+    readonly id: string;
+    readonly publisher: NormalizedAddress;
+    readonly wakeId: WakeId;
+}
+export type WakeAttemptResolution = {
+    readonly kind: 'new';
+} | {
+    readonly kind: 'duplicate';
+    readonly receipt: WakeAdmissionReceipt;
+} | {
+    readonly kind: 'jwt-id-collision';
+} | {
+    readonly kind: 'wake-id-collision';
+};
+export type WakeCommitResult = {
+    readonly kind: 'enqueued';
+    readonly receipt: WakeAdmissionReceipt;
+} | {
+    readonly kind: 'duplicate';
+    readonly receipt: WakeAdmissionReceipt;
+} | {
+    readonly kind: 'jwt-id-collision';
+} | {
+    readonly kind: 'wake-id-collision';
+};
+/**
+ * Durable linearizable admission boundary.
+ *
+ * `resolveAttempt` must atomically bind a fresh JWT id to an existing matching
+ * wake receipt. It must not consume either identity when returning `new`.
+ *
+ * `commitAuthorized` must atomically recheck both identities, persist both
+ * mappings and their stable receipt, and durably enqueue the wake (or write a
+ * transactional outbox record). A separate fallible enqueue is nonconforming.
+ */
+export interface AtomicWakeInbox {
+    commitAuthorized: (input: {
+        readonly attempt: WakeAdmissionAttempt;
+        readonly grant: AuthorizedWakeGrant;
+        readonly wake: AdmittedWake;
+    }) => Promise<WakeCommitResult>;
+    resolveAttempt: (attempt: WakeAdmissionAttempt) => Promise<WakeAttemptResolution>;
+}
+//# sourceMappingURL=admissionTypes.d.ts.map

package/dist/neutral/admissionTypes.d.ts.map

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

package/dist/neutral/admitAndEnqueue.d.ts

@@ -0,0 +1,29 @@
+import type { AtomicWakeInbox, WakeAdmissionReceipt, WakeGrantAuthorizer } from './admissionTypes.ts';
+import type { AdmittedWake } from './types.ts';
+import type { VerifiedWakeRequest } from './verifyWakeRequest.ts';
+export interface AdmitAndEnqueueInput {
+    /** Independently trusted finalized XL1 head for this admission attempt. */
+    readonly expectedHead: number;
+    readonly grants: WakeGrantAuthorizer;
+    readonly inbox: AtomicWakeInbox;
+    readonly verified: VerifiedWakeRequest;
+}
+export type AdmitAndEnqueueFailureReason = 'grant-missing' | 'grant-unavailable' | 'grant-view-invalid' | 'grant-view-stale' | 'inbox-unavailable' | 'jwt-id-collision' | 'wake-id-collision';
+export interface AdmitAndEnqueueFailure {
+    readonly details?: readonly string[];
+    readonly ok: false;
+    readonly reason: AdmitAndEnqueueFailureReason;
+}
+export interface AdmitAndEnqueueSuccess {
+    readonly disposition: 'duplicate' | 'enqueued';
+    readonly ok: true;
+    readonly receipt: WakeAdmissionReceipt;
+    readonly wake: AdmittedWake;
+}
+export type AdmitAndEnqueueResult = AdmitAndEnqueueFailure | AdmitAndEnqueueSuccess;
+/**
+ * Performs D-002 durable replay/idempotency resolution, live grant
+ * authorization, and atomic enqueue after pure request verification.
+ */
+export declare function admitAndEnqueue(input: AdmitAndEnqueueInput): Promise<AdmitAndEnqueueResult>;
+//# sourceMappingURL=admitAndEnqueue.d.ts.map

package/dist/neutral/admitAndEnqueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admitAndEnqueue.d.ts","sourceRoot":"","sources":["../../src/admitAndEnqueue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAGf,oBAAoB,EAGpB,mBAAmB,EAEpB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAEjE,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;CACvC;AAED,MAAM,MAAM,4BAA4B,GAClC,eAAe,GACf,mBAAmB,GACnB,oBAAoB,GACpB,kBAAkB,GAClB,mBAAmB,GACnB,kBAAkB,GAClB,mBAAmB,CAAA;AAEzB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAA;CAC9C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,UAAU,CAAA;IAC9C,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAC5B;AAED,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,sBAAsB,CAAA;AAEnF;;;GAGG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgBjG"}

package/dist/neutral/index.d.ts

@@ -0,0 +1,19 @@
+export type { AtomicWakeInbox, AuthorizedWakeGrant, WakeAdmissionAttempt, WakeAdmissionReceipt, WakeAttemptResolution, WakeCommitResult, WakeGrantAuthorizationDecision, WakeGrantAuthorizationDisabled, WakeGrantAuthorizationEnabled, WakeGrantAuthorizationRequest, WakeGrantAuthorizer, WakeGrantEvidence, } from './admissionTypes.ts';
+export { EVENT_KIT_REPLAY_RETENTION_SKEW_SECONDS } from './admissionTypes.ts';
+export type { AdmitAndEnqueueFailure, AdmitAndEnqueueFailureReason, AdmitAndEnqueueInput, AdmitAndEnqueueResult, AdmitAndEnqueueSuccess, } from './admitAndEnqueue.ts';
+export { admitAndEnqueue } from './admitAndEnqueue.ts';
+export type { MemoryStatementGrantGraph } from './memoryStatementGrantGraph.ts';
+export { createMemoryStatementGrantGraph } from './memoryStatementGrantGraph.ts';
+export type { MemoryWakeInbox, MemoryWakeInboxOptions, } from './memoryWakeInbox.ts';
+export { createMemoryWakeInbox } from './memoryWakeInbox.ts';
+export type { MemoryWakeQueue } from './memoryWakeQueue.ts';
+export { createMemoryWakeQueue } from './memoryWakeQueue.ts';
+export type { StatementGrantClaim, StatementGrantClaimQuery, StatementGrantObject, StatementGraphGrantReadModel, } from './statementGraphPorts.ts';
+export type { StatementGraphWakeGrantAuthorizerOptions } from './statementGraphWakeGrantAuthorizer.ts';
+export { createStatementGraphWakeGrantAuthorizer } from './statementGraphWakeGrantAuthorizer.ts';
+export type { AdmittedWake } from './types.ts';
+export type { VerifiedWakeRequest, VerifyWakeRequestFailure, VerifyWakeRequestInput, VerifyWakeRequestRejectionReason, VerifyWakeRequestResult, VerifyWakeRequestSuccess, WakeAdmissionRoute, } from './verifyWakeRequest.ts';
+export { EVENT_KIT_MAX_FUTURE_IAT_SECONDS, EVENT_KIT_MAX_JWT_LIFETIME_SECONDS, verifyWakeRequest, } from './verifyWakeRequest.ts';
+export type { LeasedWake, WakeHandler, WakeQueue, } from './wakeQueue.ts';
+export { drainQueue } from './wakeQueue.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/neutral/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,8BAA8B,EAC9B,8BAA8B,EAC9B,6BAA6B,EAC7B,6BAA6B,EAC7B,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,uCAAuC,EAAE,MAAM,qBAAqB,CAAA;AAC7E,YAAY,EACV,sBAAsB,EACtB,4BAA4B,EAC5B,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,YAAY,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAC/E,OAAO,EAAE,+BAA+B,EAAE,MAAM,gCAAgC,CAAA;AAChF,YAAY,EACV,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,0BAA0B,CAAA;AACjC,YAAY,EAAE,wCAAwC,EAAE,MAAM,wCAAwC,CAAA;AACtG,OAAO,EAAE,uCAAuC,EAAE,MAAM,wCAAwC,CAAA;AAChG,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,gCAAgC,EAChC,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,gCAAgC,EAChC,kCAAkC,EAClC,iBAAiB,GAClB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,UAAU,EACV,WAAW,EACX,SAAS,GACV,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA"}