@voltro/protocol 0.79.1 → 0.81.0

package/dist/jwt.d.ts

@@ -339,6 +339,14 @@ declare const Subject: Schema.Union<[Schema.Struct<{
     tenantId: typeof Schema.Null;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["service"]>;
+    id: typeof Schema.String;
+    /** The calling app's name, as the callee lists it in `serviceCallers`. */
+    service: typeof Schema.String;
+    tenantId: typeof Schema.Null;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>]>;
 
 declare type Subject = typeof Subject.Type;

package/dist/rest.d.ts

@@ -30,6 +30,9 @@ declare interface ActionProcedureDescriptor<Name extends string, Input extends S
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this action into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this action into the auto-synthesized agent toolset (innovation/07). */
@@ -138,7 +141,7 @@ export declare const collectPublicApiRoutes: (entries: ReadonlyArray<PublicApiEn
  * because that is where the normalised decision lands, and because every
  * enforcement path reads the descriptor's array and nothing else.
  */
-declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec>;
+declare type DeclaredAccess<Input = unknown> = ReadonlyArray<AnyGuardSpec<Input> | OpenAccessSpec | ServiceAccessSpec>;
 
 /** The `_tag` literals a descriptor's `error:` union declares (empty for none). */
 export declare const declaredErrorTags: (error: Schema.Schema.All | undefined) => ReadonlySet<string>;
@@ -178,15 +181,16 @@ export declare const deriveResource: (tag: string, spec: PublicApiSpec, descript
 
 /**
  * Dispatch a request across REST routes that SHARE a path. Every REST route
- * mounts as `*` and gates its own method, returning a precise 405 BEFORE any
- * side effect when the method isn't its own — so probing the group in order and
- * taking the FIRST non-405 result yields the route that owns the request's
- * method. This is what lets the standard GET + POST on one resource path
- * coexist: the runtime's rpc server (`rpcServer.ts`, started by both boot
- * paths) mounts ONE dispatcher per path (the underlying
- * router rejects two mounts on the same `(method, path)`). A single-route group
- * returns that route's result directly (its own 405 included); when no route in
- * the group owns the method, the last 405 stands.
+ * gates its own method, returning a precise 405 BEFORE any side effect when the
+ * method isn't its own — so probing the group in order and taking the FIRST
+ * non-405 result yields the route that owns the request's method. This is what
+ * lets the standard GET + POST on one resource path coexist: `rpcServer.ts` in
+ * `@voltro/runtime` mounts ONE dispatcher per
+ * path (the underlying router rejects two mounts on the same
+ * `(method, path)`). A single-route group returns that route's result directly
+ * (its own 405 included); when no route in the group owns the method, the last
+ * 405 stands — its `Allow` names every method the path serves, because
+ * `restRoutesToHttpRoutes` gives each route its path's full set.
  *
  * `group` must be non-empty (the serve pipeline only builds a dispatcher for a
  * path that has at least one route).
@@ -283,14 +287,24 @@ declare interface IdempotencyStore {
     /** Current record for (scope, key), or null. Read-side (inspect/dashboard). */
     readonly get: (scope: string, key: string) => Promise<IdempotencyRecord | null>;
     /**
-     * Atomically claim (scope, key) IF absent OR stale (older than `ttlMs`):
+     * Atomically claim (scope, key) IF absent OR stale — a COMPLETED record older
+     * than `ttlMs` (the replay window), or an IN-FLIGHT one whose lease
+     * (`inFlightLeaseMs`, renewed by the live handler) lapsed:
      * write a fresh `in_flight` row and return `'claimed'`. Otherwise return the
      * EXISTING (still-fresh) record. The atomicity here is the whole game — two
      * concurrent same-key requests both hit this, exactly one gets `'claimed'`,
      * the loser reads the winner's record. In SQL this is one
      * `INSERT … ON CONFLICT DO UPDATE … WHERE existing.createdAt < now - ttl`.
      */
-    readonly claim: (scope: string, key: string, now: number, ttlMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    readonly claim: (scope: string, key: string, now: number, ttlMs: number, inFlightLeaseMs: number) => Promise<'claimed' | IdempotencyRecord>;
+    /**
+     * Extend a RUNNING claim's lease: bump its timestamp while it is still
+     * `in_flight` (a completed or released claim is left alone). The server calls
+     * it while the handler runs; a process that dies stops calling it, and its
+     * claim goes stale after `inFlightLeaseMs` instead of after the whole replay
+     * window.
+     */
+    readonly renew: (scope: string, key: string, now: number) => Promise<void>;
     /** Flip the claim to `completed` and store the response. */
     readonly complete: (scope: string, key: string, response: IdempotencyResponse, now: number) => Promise<void>;
     /** Drop the claim (handler errored → a retry may re-process). */
@@ -370,6 +384,9 @@ declare interface MutationProcedureDescriptor<Name extends string, Input extends
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this mutation into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this mutation into the auto-synthesized agent toolset (innovation/07). */
@@ -504,11 +521,17 @@ declare interface PluginErrorSchema {
 
 /** A public raw-HTTP route a plugin serves on the framework listener. */
 declare interface PluginHttpRoute {
-    /** HTTP method, or `'*'` for any (the handler decides). PATCH/HEAD/OPTIONS
-     *  are first-class — the REST desugar used to mount `'*'` partly BECAUSE
-     *  this union lacked PATCH; that reason is gone (the `'*'` mount remains
-     *  for its other job: one dispatcher per shared path + a precise 405). */
+    /** HTTP method, or `'*'` for any (the handler decides). The server mounts the
+     *  path for exactly the methods its routes declare; `'*'` mounts it for every
+     *  method the router knows (34), so keep that for a route that really serves
+     *  them — see `answersOtherMethods` for one that only wants to refuse them. */
     readonly method: '*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /** `true`: the handler gates its own method, so a request with a method the
+     *  path does not declare is still handed to it — to answer with a precise
+     *  `405` and `Allow` instead of the router's `404`. The path is still mounted
+     *  only for `method`. A REST route sets it. Without it, a route that declares
+     *  one method never sees another. */
+    readonly answersOtherMethods?: boolean | undefined;
     /** Absolute path, e.g. `/_voltro/storage`. Matched byte for byte: the
      *  router folds case and a trailing slash to FIND the route, the dispatcher
      *  then asks whether the request's path is one the route declared — so
@@ -1052,6 +1075,9 @@ declare interface QueryProcedureDescriptor<Name extends string, Input extends Sc
      *  `openAccess: '<why>'`. Mutually exclusive with `guards`; together they are
      *  the only two shapes `security.defaultDeny` accepts. */
     readonly openAccess: string | undefined;
+    /** Only these apps of the project may call this procedure — see `service` on
+     *  the definer's options. Absent → the app's own clients call it. */
+    readonly service: ServiceSpec | undefined;
     /** Opt this query into a public REST endpoint (innovation/11). */
     readonly publicApi: PublicApiSpec | undefined;
     /** Opt this query into the auto-synthesized agent toolset (innovation/07). */
@@ -1289,6 +1315,9 @@ export declare interface RestRouteContext {
      *  REST handlers on the same capability surface as query/mutation/action
      *  handlers without creating a protocol-to-runtime package dependency. */
     readonly app?: unknown;
+    /** The caller's address, resolved through `security.trustedProxies` — the
+     *  value the listener's per-IP shield counts. Absent when unknown. */
+    readonly remoteAddr?: string;
 }
 
 export declare interface RestRouteDescriptor<I, O> {
@@ -1487,6 +1516,37 @@ export declare const routeAcceptsPath: (route: {
     readonly match?: "prefix" | "exact" | undefined;
 }, path: string) => boolean;
 
+/**
+ * The runtime-erased form of a procedure's `service: { callers }` — "only these
+ * apps of the project may call this, and nobody else".
+ *
+ * A guard entry for the reason `OpenAccessSpec` is one: every enforcement path
+ * is handed the `guards` array and nothing else, so a decision that lived on a
+ * separate descriptor field would be enforced by the paths somebody remembered
+ * and skipped by the rest.
+ *
+ * It admits exactly a `service` subject whose name is listed. `admin:full` does
+ * NOT bypass it: a service procedure is a machine contract between two apps,
+ * and a browser session holding the admin scope is not one of the parties.
+ */
+declare interface ServiceAccessSpec {
+    /** The calling apps' names, as the callee declares them in `serviceCallers`.
+     *  Non-empty by construction — the definers refuse an empty list. */
+    readonly service: ReadonlyArray<string>;
+}
+
+/**
+ * A service procedure's declaration: which apps of the project may call it.
+ *
+ *     service: { callers: ['worker'] }
+ *
+ * The names are the CALLING apps' names as this app lists them in
+ * `serviceCallers` — the same name the caller's credential resolves to.
+ */
+declare interface ServiceSpec {
+    readonly callers: ReadonlyArray<string>;
+}
+
 /**
  * Build a streaming (Server-Sent Events) handler result. `subscribe` gets an
  * `emit` for one already-framed SSE chunk and MUST return an unsubscribe, which
@@ -1555,6 +1615,14 @@ declare const Subject: Schema.Union<[Schema.Struct<{
     tenantId: typeof Schema.Null;
     scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
     metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["service"]>;
+    id: typeof Schema.String;
+    /** The calling app's name, as the callee lists it in `serviceCallers`. */
+    service: typeof Schema.String;
+    tenantId: typeof Schema.Null;
+    scopes: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>]>;
 
 declare type Subject = typeof Subject.Type;