- src/platform/: SiaxRequestContext + propagation headers + 12 canonical
error codes (documented mirror of cl0ud packages/contract), SiaxError,
resource refs (st0re:artifact:...), and the §3/§10 dependency-mode guard:
production runtime + unconfigured dependency/store => hard
DEPENDENCY_UNAVAILABLE at construction, never silent mock/in-memory.
- src/clients/: all four platform clients rewritten against the REAL wire
contracts verified on sibling main branches this session:
* cl0ud: POST /api/policy/evaluate ({data} envelope, allow+requiresApproval)
- the old /v1/cl0ud/policies/evaluate path never existed on CL0UD
* st0re: camelCase ArtifactInput on /v1/st0re/artifacts/register incl.
X-Tenant-Id/X-Actor-Id + X-Idempotency-Key - the old snake_case body
would have been a 400 against the live registry
* n0d: required_role + resource_requirements + body idempotency_key +
CloudEvents callback_url per n0d createJobSchema; adds getJob/getJobResult
* aud0: /v1/aud0/openlineage is AUD0's only lineage ingest -
/v1/aud0/lineage/events never existed; legacy shape converts to a
spec-shaped OpenLineage RunEvent (deterministic runId dedup)
- src/lineage/: OpenLineage subset types + LineageEmitter (never-throw,
§16 evidence semantics)
- shared SiaxHttp transport: timeouts, typed SiaxError mapping, context
propagation, no raw upstream bodies in errors
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
105 lines
4.5 KiB
TypeScript
105 lines
4.5 KiB
TypeScript
/**
|
|
* src/platform/siax-context.ts
|
|
* =============================
|
|
* MIRROR of cl0ud's canonical cross-product request context
|
|
* (`sax3l/cl0ud` `packages/contract/src/request-context.ts`, merged to cl0ud
|
|
* main 2026-08-31). Mirrored — NOT imported — because `@siax/contract` is not
|
|
* published to a registry this repo consumes yet; the mirror posture is the
|
|
* same one cl0ud itself documents for its platform-core `ErrorCode` mirror
|
|
* ("KEEP ALIGNED; drift is a review catch and a test failure").
|
|
* tests/contracts/siax-context.contract.test.ts pins every header name and
|
|
* field so drift against the canonical source fails loudly here.
|
|
*
|
|
* TRUST BOUNDARY (verbatim from the canonical source): this context is a
|
|
* CARRIER, not a VERIFIER. A receiving service derives its tenant from the
|
|
* VERIFIED caller; the `x-tenant-id` propagation header is honoured only for
|
|
* a verified machine/service principal. The cryptographic binding is the
|
|
* service credential on the Authorization header — this context rides
|
|
* alongside it for scoping, policy and tracing.
|
|
*/
|
|
|
|
/** The canonical SIAX cross-product request context (Master-DoD §4). */
|
|
export interface SiaxRequestContext {
|
|
/** The tenant this call acts for (`t_<slug>` spine). Server-derived. */
|
|
tenantId: string;
|
|
/** The bound project within the tenant, when the operation is project-scoped. */
|
|
projectId?: string;
|
|
/** The acting subject: a user `sub`, or a service/machine identity id. */
|
|
actorId: string;
|
|
/** The capability being invoked — canonical dotted registry id, e.g. `0pt.search.query.v1`. */
|
|
capability: string;
|
|
/** Optional GDPR/purpose-limitation tag, e.g. `valuation`, `support`, `billing`. */
|
|
purpose?: string;
|
|
/** Correlation id shared by every hop of one logical operation. */
|
|
correlationId: string;
|
|
/** The id of the event/request that CAUSED this one (event-chain lineage). */
|
|
causationId?: string;
|
|
/** Distributed-tracing trace id (W3C trace-context compatible where possible). */
|
|
traceId?: string;
|
|
/** Idempotency key for retried writes — same key ⇒ same effect, exactly once. */
|
|
idempotencyKey?: string;
|
|
}
|
|
|
|
/**
|
|
* Canonical wire headers for propagating a {@link SiaxRequestContext} on
|
|
* service-to-service calls. Names are pinned to cl0ud's
|
|
* `SIAX_CONTEXT_HEADERS` verbatim.
|
|
*/
|
|
export const SIAX_CONTEXT_HEADERS = {
|
|
tenant: "x-tenant-id",
|
|
actor: "x-actor-id",
|
|
capability: "x-siax-capability",
|
|
purpose: "x-siax-purpose",
|
|
project: "x-siax-project-id",
|
|
correlation: "x-siax-correlation-id",
|
|
causation: "x-siax-causation-id",
|
|
trace: "x-siax-trace-id",
|
|
idempotency: "idempotency-key",
|
|
} as const;
|
|
|
|
/**
|
|
* Serialize a context to the canonical propagation headers for an OUTBOUND
|
|
* service-to-service call. The caller adds its own service `Authorization` —
|
|
* this function deliberately has no way to carry a token.
|
|
*/
|
|
export function toPropagationHeaders(ctx: SiaxRequestContext): Record<string, string> {
|
|
const h: Record<string, string> = {
|
|
[SIAX_CONTEXT_HEADERS.tenant]: ctx.tenantId,
|
|
[SIAX_CONTEXT_HEADERS.actor]: ctx.actorId,
|
|
[SIAX_CONTEXT_HEADERS.capability]: ctx.capability,
|
|
[SIAX_CONTEXT_HEADERS.correlation]: ctx.correlationId,
|
|
};
|
|
if (ctx.projectId) h[SIAX_CONTEXT_HEADERS.project] = ctx.projectId;
|
|
if (ctx.purpose) h[SIAX_CONTEXT_HEADERS.purpose] = ctx.purpose;
|
|
if (ctx.causationId) h[SIAX_CONTEXT_HEADERS.causation] = ctx.causationId;
|
|
if (ctx.traceId) h[SIAX_CONTEXT_HEADERS.trace] = ctx.traceId;
|
|
if (ctx.idempotencyKey) h[SIAX_CONTEXT_HEADERS.idempotency] = ctx.idempotencyKey;
|
|
return h;
|
|
}
|
|
|
|
/**
|
|
* Pure structural validation of a candidate context (e.g. before persisting
|
|
* to an audit/lineage record). Returns a list of problems — empty means
|
|
* valid. NOT an authorization check.
|
|
*/
|
|
export function validateSiaxRequestContext(ctx: Partial<SiaxRequestContext>): string[] {
|
|
const problems: string[] = [];
|
|
const requireNonEmpty = (field: keyof SiaxRequestContext) => {
|
|
const v = ctx[field];
|
|
if (typeof v !== "string" || v.trim().length === 0) {
|
|
problems.push(`${field} is required and must be a non-empty string`);
|
|
}
|
|
};
|
|
requireNonEmpty("tenantId");
|
|
requireNonEmpty("actorId");
|
|
requireNonEmpty("capability");
|
|
requireNonEmpty("correlationId");
|
|
for (const field of ["projectId", "purpose", "causationId", "traceId", "idempotencyKey"] as const) {
|
|
const v = ctx[field];
|
|
if (v !== undefined && (typeof v !== "string" || v.trim().length === 0)) {
|
|
problems.push(`${field}, when present, must be a non-empty string`);
|
|
}
|
|
}
|
|
return problems;
|
|
}
|