@farthershore/backend 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to the runtime backend SDK are documented here. This SDK
 versions independently from the frontend and business SDKs. Pre-1.0: minor
 versions may include breaking changes.
 
+## [0.17.0]
+
+### Changed — BREAKING
+
+- `RUNTIME_TOKEN_CAPABILITIES` is renamed `RUNTIME_TOKEN_OPERATIONS`, and the
+  type `RuntimeTokenCapability` is renamed `RuntimeTokenOperation`. The values
+  are operations, not capabilities, and the old names contradicted the runtime
+  contract they mirror. Update imports; no behaviour change.
+
+### Added
+
+- `credentialKind()` and `isPortalSession()` — route-surface credential-kind
+  derivation from the signed principal. No new claim is required; both are
+  derived from what the gateway already signs.
+
 ## [0.16.0]
 
 Consumer-principal runtime. Every verified request now carries a typed

package/README.md

@@ -12,7 +12,7 @@ graceful lifecycle (health + shutdown). Everything else — your business, backe
 and environment ids, the verification keys, and the metering endpoint — is
 fetched automatically from the token at startup.
 
-> **Status: `0.16.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.17.0`.** Pre-1.0: minor releases may include breaking changes, so
 > pin this package to an exact version (or a patch-only range) and upgrade
 > deliberately.
 

package/dist/adapters/express.js

@@ -18,7 +18,9 @@ var FartherShoreError = class extends Error {
   }
 };
 function statusForCode(code) {
-  return code === "body_too_large" ? 413 : 401;
+  if (code === "body_too_large") return 413;
+  if (code === "surface_not_allowed") return 403;
+  return 401;
 }
 
 // src/core/permissions.ts

package/dist/generated/runtime-contract.js

@@ -166,7 +166,8 @@ var RUNTIME_ERROR_CODES = {
   invalidToken: "invalid_token",
   contextUnverified: "context_unverified",
   memberSubjectRequired: "member_subject_required",
-  serviceSubjectRequired: "service_subject_required"
+  serviceSubjectRequired: "service_subject_required",
+  surfaceNotAllowed: "surface_not_allowed"
 };
 var RUNTIME_METERING_CONTRACT = {
   endpoint: "/v1/metering/events",

package/dist/index.js

@@ -217,7 +217,8 @@ var RUNTIME_ERROR_CODES = {
   invalidToken: "invalid_token",
   contextUnverified: "context_unverified",
   memberSubjectRequired: "member_subject_required",
-  serviceSubjectRequired: "service_subject_required"
+  serviceSubjectRequired: "service_subject_required",
+  surfaceNotAllowed: "surface_not_allowed"
 };
 var RUNTIME_RESPONSE_METERING_CONTRACT = {
   headers: {
@@ -284,7 +285,9 @@ var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
   [RUNTIME_ERROR_CODES.bodyTooLarge]: "VALIDATION_ERROR",
   // Consumer-principal wave — route subject-requirement faults → FORBIDDEN (403).
   [RUNTIME_ERROR_CODES.memberSubjectRequired]: "FORBIDDEN",
-  [RUNTIME_ERROR_CODES.serviceSubjectRequired]: "FORBIDDEN"
+  [RUNTIME_ERROR_CODES.serviceSubjectRequired]: "FORBIDDEN",
+  // A visible route whose surface set excludes the caller → 403.
+  [RUNTIME_ERROR_CODES.surfaceNotAllowed]: "FORBIDDEN"
 };
 function runtimeErrorToErrorCode(code) {
   return RUNTIME_ERROR_CODE_TO_ERROR_CODE[code] ?? "INTERNAL_ERROR";
@@ -294,16 +297,16 @@ var RUNTIME_TOKEN_PREFIXES = {
   live: "fsrt_live_",
   test: "fsrt_test_"
 };
-var RUNTIME_TOKEN_CAPABILITIES = [
+var RUNTIME_TOKEN_OPERATIONS = [
   "gateway_verification",
   "metering",
   "health",
   "tunnel",
-  // Hand-maintained mirror of @farthershore/contracts RUNTIME_TOKEN_CAPABILITIES
+  // Hand-maintained mirror of @farthershore/contracts RUNTIME_TOKEN_OPERATIONS
   // (`runtime.ts`). Bound to that source by the SET-EQUALITY + ORDER assertions
   // in `deny-taxonomy-drift.test.ts` (test-only contracts devDep) — NOT by the
   // generated runtime-contract.ts, which mirrors only RUNTIME_ERROR_CODES.
-  // `drift_report` is the opt-in capability for reporting route drift.
+  // `drift_report` is the opt-in operation for reporting route drift.
   "drift_report"
 ];
 var RUNTIME_HEADER_NAMES = {
@@ -457,7 +460,9 @@ var FartherShoreError = class extends Error {
   }
 };
 function statusForCode(code) {
-  return code === "body_too_large" ? 413 : 401;
+  if (code === "body_too_large") return 413;
+  if (code === "surface_not_allowed") return 403;
+  return 401;
 }
 
 // src/core/bootstrap.ts
@@ -1913,8 +1918,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.16.0".length > 0 ? "0.16.0" : "0.0.0-dev";
-var CONTRACTS_FP = "c3961d4ea07ff178".length > 0 ? "c3961d4ea07ff178" : "0000000000000000";
+var SDK_VERSION = "0.17.0".length > 0 ? "0.17.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;
@@ -2378,6 +2382,16 @@ function requireService(ctx) {
   }
   return subject;
 }
+function credentialKind(ctx) {
+  const subject = ctx.principal?.subject;
+  if (!subject) return void 0;
+  if (subject.kind === "service") return "api_key";
+  return subject.via === "session" ? "portal_session" : "api_key";
+}
+function isPortalSession(ctx) {
+  const kind = credentialKind(ctx);
+  return kind === void 0 ? void 0 : kind === "portal_session";
+}
 
 // src/testing/signers.ts
 import { generateKeyPairSync, randomBytes } from "node:crypto";
@@ -2652,7 +2666,7 @@ function createDevGateway(options) {
       name: "Dev Backend"
     },
     environment: { id: null, kind: "test" },
-    capabilities: ["gateway_verification", "metering", "health"],
+    operations: ["gateway_verification", "metering", "health"],
     verification: {
       required: options.mode === "simulated",
       jwksUrl: DEV_JWKS_URL,
@@ -3185,7 +3199,7 @@ export {
   RUNTIME_ERROR_CODE_TO_ERROR_CODE,
   RUNTIME_HEADER_NAMES,
   RUNTIME_REPLAY_WINDOW_SECONDS,
-  RUNTIME_TOKEN_CAPABILITIES,
+  RUNTIME_TOKEN_OPERATIONS,
   RUNTIME_TOKEN_PREFIXES,
   STREAMING_EXEMPT_BODY_HASH,
   ShutdownManager,
@@ -3196,11 +3210,13 @@ export {
   createExpressHandler,
   createExpressMiddleware,
   createUsage,
+  credentialKind,
   decodeContextClaims,
   fartherShore,
   hasPermission,
   hashBody2 as hashBody,
   initFromEnv2 as initFromEnv,
+  isPortalSession,
   nodeSpawn,
   permissionGrants,
   permissionSatisfies,

package/dist/testing/index.js

@@ -220,7 +220,8 @@ var RUNTIME_ERROR_CODES = {
   invalidToken: "invalid_token",
   contextUnverified: "context_unverified",
   memberSubjectRequired: "member_subject_required",
-  serviceSubjectRequired: "service_subject_required"
+  serviceSubjectRequired: "service_subject_required",
+  surfaceNotAllowed: "surface_not_allowed"
 };
 var RUNTIME_RESPONSE_METERING_CONTRACT = {
   headers: {
@@ -287,7 +288,9 @@ var RUNTIME_ERROR_CODE_TO_ERROR_CODE = {
   [RUNTIME_ERROR_CODES.bodyTooLarge]: "VALIDATION_ERROR",
   // Consumer-principal wave — route subject-requirement faults → FORBIDDEN (403).
   [RUNTIME_ERROR_CODES.memberSubjectRequired]: "FORBIDDEN",
-  [RUNTIME_ERROR_CODES.serviceSubjectRequired]: "FORBIDDEN"
+  [RUNTIME_ERROR_CODES.serviceSubjectRequired]: "FORBIDDEN",
+  // A visible route whose surface set excludes the caller → 403.
+  [RUNTIME_ERROR_CODES.surfaceNotAllowed]: "FORBIDDEN"
 };
 var FS_RUNTIME_TOKEN_ENV = "FS_RUNTIME_TOKEN";
 var RUNTIME_TOKEN_PREFIXES = {
@@ -444,7 +447,9 @@ var FartherShoreError = class extends Error {
   }
 };
 function statusForCode(code) {
-  return code === "body_too_large" ? 413 : 401;
+  if (code === "body_too_large") return 413;
+  if (code === "surface_not_allowed") return 403;
+  return 401;
 }
 
 // src/core/jwks.ts
@@ -868,7 +873,7 @@ function createDevGateway(options) {
       name: "Dev Backend"
     },
     environment: { id: null, kind: "test" },
-    capabilities: ["gateway_verification", "metering", "health"],
+    operations: ["gateway_verification", "metering", "health"],
     verification: {
       required: options.mode === "simulated",
       jwksUrl: DEV_JWKS_URL,
@@ -2144,8 +2149,7 @@ function headerGetter(headers) {
 
 // src/core/runtime.ts
 var DEFAULT_CORE_URL = "https://core.farthershore.com";
-var SDK_VERSION = "0.16.0".length > 0 ? "0.16.0" : "0.0.0-dev";
-var CONTRACTS_FP = "c3961d4ea07ff178".length > 0 ? "c3961d4ea07ff178" : "0000000000000000";
+var SDK_VERSION = "0.17.0".length > 0 ? "0.17.0" : "0.0.0-dev";
 var FartherShore = class {
   bootstrapClient;
   fetchImpl;

package/dist/types/core/errors.d.ts

@@ -21,6 +21,9 @@ export declare class FartherShoreError extends Error {
 }
 /**
  * Map a runtime error code to its fail-closed HTTP status. Oversized bodies are
- * the only non-401 (413); all other verification failures are 401.
+ * 413; a wrong-credential-surface denial is 403 (the caller IS authenticated,
+ * just not on a surface this route admits — mirrors the canonical
+ * `surface_not_allowed → FORBIDDEN` mapping in contracts/error-codes.ts);
+ * all other verification failures are 401.
  */
 export declare function statusForCode(code: RuntimeErrorCode): number;

package/dist/types/core/runtime.d.ts

@@ -69,7 +69,6 @@ export type FartherShoreInitOptions = {
     nonceStore?: NonceStore;
 };
 export declare const SDK_VERSION: string;
-export declare const CONTRACTS_FP: string;
 /**
  * The runtime instance. Lazily bootstraps; holds the JWKS client, nonce cache,
  * metering buffer, and shutdown hooks.

package/dist/types/core/subject.d.ts

@@ -23,3 +23,23 @@ export declare function requireMember(ctx: PrincipalCarrier): MemberSubject;
  * Throws `service_subject_required` when the subject is a member (or absent).
  */
 export declare function requireService(ctx: PrincipalCarrier): ServiceSubject;
+/**
+ * The credential SURFACE behind a verified request, DERIVED from the signed
+ * principal (route-surfaces wave) — no new claim, no spoofable header. A member
+ * subject carries `via`; a service subject is always key-borne. Returns
+ * `undefined` when the request carried no verified principal (identity-less), so
+ * a caller can distinguish "not a portal session" from "unknown".
+ *
+ *   - `"portal_session"` ⟺ a member via a browser session (`fsc_`).
+ *   - `"api_key"`        ⟺ a member's personal key OR any service key (`fsk_`).
+ */
+export declare function credentialKind(ctx: PrincipalCarrier): "portal_session" | "api_key" | undefined;
+/**
+ * True when the verified request came from the managed portal UI (a member
+ * browser session), false when it came from an API key, and `undefined` when
+ * there is no verified principal. Convenience over {@link credentialKind} for
+ * the common portal-vs-API branch (e.g. richer UI payloads for portal callers).
+ * The gateway's `enforce-surface` middleware is the SECURITY boundary; this is
+ * for in-handler ergonomics.
+ */
+export declare function isPortalSession(ctx: PrincipalCarrier): boolean | undefined;

package/dist/types/generated/runtime-contract.d.ts

@@ -140,6 +140,7 @@ export declare const RUNTIME_ERROR_CODES: {
     readonly contextUnverified: "context_unverified";
     readonly memberSubjectRequired: "member_subject_required";
     readonly serviceSubjectRequired: "service_subject_required";
+    readonly surfaceNotAllowed: "surface_not_allowed";
 };
 export type RuntimeErrorCode = (typeof RUNTIME_ERROR_CODES)[keyof typeof RUNTIME_ERROR_CODES];
 export declare const RUNTIME_METERING_CONTRACT: {

package/dist/types/index.d.ts

@@ -6,7 +6,7 @@ export { FartherShoreError, statusForCode } from "./core/errors.js";
 export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
 export { verifyContext, decodeContextClaims, principalFromContextClaims, } from "./core/verifyContext.js";
 export type { FartherShoreSignedContext, ConsumerPrincipal, } from "./core/verifyContext.js";
-export { requireMember, requireService, type MemberSubject, type ServiceSubject, type PrincipalCarrier, } from "./core/subject.js";
+export { requireMember, requireService, credentialKind, isPortalSession, type MemberSubject, type ServiceSubject, type PrincipalCarrier, } from "./core/subject.js";
 export { hasPermission, requirePermission, permissionGrants, permissionSatisfies, FartherShorePermissionError, type PermissionCarrier, } from "./core/permissions.js";
 export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions, type NonceStore, } from "./core/nonceCache.js";
@@ -18,7 +18,7 @@ export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
 export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";
 export type { FartherShoreTunnelOptions } from "./core/runtime.js";
 export { createExpressMiddleware, createExpressHandler, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type MiddlewareOptions, type VerifiedExpressHandler, type VerifiedPrincipalContext, } from "./adapters/express.js";
-export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_CAPABILITIES, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenCapability, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, RUNTIME_ERROR_CODE_TO_ERROR_CODE, runtimeErrorToErrorCode, type LimitDescriptor, type RuntimeMappedErrorCode, } from "./runtime-types.js";
+export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_OPERATIONS, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenOperation, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, RUNTIME_ERROR_CODE_TO_ERROR_CODE, runtimeErrorToErrorCode, type LimitDescriptor, type RuntimeMappedErrorCode, } from "./runtime-types.js";
 export { RUNTIME_ERROR_CODES } from "./generated/runtime-contract.js";
 export { hashBody, buildCanonicalSigningString, canonicalizeQuery, signCanonicalString, verifyCanonicalSignature, runtimeTokenKind, } from "./runtime-signing.js";
 export { createUsage, withUsage, computeMeteringHeaders, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, type MeteringHeaders, type ComputeMeteringOptions, type ResponseMeteringUsagePayload, } from "./response-metering.js";

package/dist/types/runtime-types.d.ts

@@ -119,8 +119,8 @@ export declare const RUNTIME_TOKEN_PREFIXES: {
     readonly test: "fsrt_test_";
 };
 export type RuntimeTokenKind = keyof typeof RUNTIME_TOKEN_PREFIXES;
-export declare const RUNTIME_TOKEN_CAPABILITIES: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];
-export type RuntimeTokenCapability = (typeof RUNTIME_TOKEN_CAPABILITIES)[number];
+export declare const RUNTIME_TOKEN_OPERATIONS: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];
+export type RuntimeTokenOperation = (typeof RUNTIME_TOKEN_OPERATIONS)[number];
 export declare const RUNTIME_HEADER_NAMES: {
     readonly signature: "x-fs-signature";
     readonly keyId: "x-fs-key-id";
@@ -237,7 +237,7 @@ export type RuntimeBootstrapResponse = {
         id: string | null;
         kind: RuntimeEnvironmentKind;
     };
-    capabilities: RuntimeTokenCapability[];
+    operations: RuntimeTokenOperation[];
     verification: RuntimeVerificationConfig;
     metering: RuntimeMeteringConfig;
     transport: RuntimeTransportConfig;
@@ -273,8 +273,6 @@ export type RuntimePostStreamUsageEvent = {
     measureContext?: Record<string, unknown>;
     signature: string;
 };
-export declare const RUNTIME_READINESS_STATES: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
-export type RuntimeReadinessState = (typeof RUNTIME_READINESS_STATES)[number];
 export type RuntimeHealthReport = {
     runtimeToken: boolean;
     bootstrap: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/backend",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Farther Shore backend SDK for builder upstreams: signed response usage, fail-closed gateway request verification, health, and lifecycle from FS_RUNTIME_TOKEN",
   "type": "module",
   "main": "./dist/index.js",