@rikalabs/akter 0.1.0-alpha.0

package/dist/serve/assertion/verify.js

@@ -0,0 +1,189 @@
+import { Clock, DateTime, Duration, Effect, Option, Result, Schema, Semaphore } from "effect";
+import { Base64Url } from "effect/encoding";
+import { Headers, HttpClient } from "effect/http";
+import { ActorUnavailable } from "../../errors/actor.js";
+import { Anonymous, User } from "../../identity/caller.js";
+import { bearerToken, Credential, unauthorized, } from "../auth.js";
+import { ASSERTION_HEADER, ASSERTION_TYPE, KEY_REFRESH_TYPE } from "./binding.js";
+/** An edge verification key: an Ed25519 public JWK, valid from `nbf` until `exp` (epoch seconds). */
+export const AssertionKey = Schema.Struct({
+    kid: Schema.NonEmptyString,
+    kty: Schema.Literal("OKP"),
+    crv: Schema.Literal("Ed25519"),
+    x: Schema.NonEmptyString,
+    nbf: Schema.optionalKey(Schema.Finite),
+    exp: Schema.optionalKey(Schema.Finite),
+});
+/** The key set the control plane publishes for runners. */
+export const AssertionKeySet = Schema.Struct({ keys: Schema.Array(AssertionKey) });
+/** The most an assertion may live, from `iat` to `exp`. */
+export const MAX_ASSERTION_SECONDS = 60;
+/** Clock skew allowed on `iat` and `exp`; edge and runners run synchronized clocks. */
+export const ASSERTION_SKEW_MS = 5_000;
+/** An unknown `kid` rereads the key set at most this often. */
+const UNKNOWN_KID_REFRESH_MS = 60_000;
+/** The JWS header of type `typ`. EdDSA with Ed25519 only: `none` and every other algorithm are refused. */
+const headerOf = (typ) => Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Struct({
+    alg: Schema.Literal("EdDSA"),
+    typ: Schema.Literal(typ),
+    kid: Schema.NonEmptyString,
+    crit: Schema.optionalKey(Schema.Never),
+})));
+const decodeAssertionHeader = headerOf(ASSERTION_TYPE);
+const decodeRefreshHeader = headerOf(KEY_REFRESH_TYPE);
+/** The claims of an edge's key-set refresh push. */
+export const KeyRefreshClaims = Schema.Struct({
+    iss: Schema.String,
+    aud: Schema.String,
+    iat: Schema.Finite,
+    exp: Schema.Finite,
+});
+const decodeRefreshClaims = Schema.decodeUnknownOption(Schema.fromJsonString(KeyRefreshClaims));
+const Digest = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/u));
+/** The claims an edge signs; `actor`, `id`, `member`, and `cid` are there for logs. */
+export const AssertionClaims = Schema.Struct({
+    iss: Schema.String,
+    aud: Schema.String,
+    region: Schema.String,
+    iat: Schema.Finite,
+    exp: Schema.Finite,
+    tenant: Schema.String,
+    caller: Schema.Union([User, Anonymous]),
+    req: Digest,
+    /** The streaming session id, on assertions for a WebSocket open or renewal. */
+    sid: Schema.optionalKey(Schema.NonEmptyString),
+    /** The external credential's own expiry in epoch seconds, which caps a live session. */
+    cexp: Schema.optionalKey(Schema.Finite),
+    actor: Schema.optionalKey(Schema.String),
+    id: Schema.optionalKey(Schema.String),
+    member: Schema.optionalKey(Schema.String),
+    cid: Schema.optionalKey(Schema.String),
+});
+const decodeClaims = Schema.decodeUnknownOption(Schema.fromJsonString(AssertionClaims));
+const decodeKeySet = Schema.decodeUnknownEffect(AssertionKeySet);
+const invalid = unauthorized("invalid_credentials");
+const utf8 = new TextEncoder();
+const headerToken = (request) => Option.match(Headers.get(request.headers, ASSERTION_HEADER), {
+    onNone: () => Effect.fail(unauthorized("missing_credentials")),
+    onSome: (value) => Effect.succeed(value.trim()),
+});
+/** The compact JWS from a WebSocket frame's `Bearer` credential, or from `durable-assertion`. */
+const tokenOf = (request) => request.credential === undefined ? headerToken(request) : bearerToken(request);
+const verifySignature = Effect.fnUntraced(function* (key, signature, signed) {
+    const imported = yield* Effect.tryPromise({
+        try: () => crypto.subtle.importKey("jwk", { kty: key.kty, crv: key.crv, x: key.x }, { name: "Ed25519" }, false, ["verify"]),
+        catch: () => invalid,
+    });
+    return yield* Effect.tryPromise({
+        try: () => crypto.subtle.verify({ name: "Ed25519" }, imported, new Uint8Array(signature), utf8.encode(signed)),
+        catch: () => invalid,
+    });
+});
+/**
+ * Verifies the hosted edge's signed assertion, the only provider a hosted
+ * runner uses. It checks the signature, key, issuer, deployment, region, and
+ * lifetime here; the server then checks the request binding against the
+ * request it received before any turn.
+ *
+ * A key set older than `refreshEvery` is reread before use, and a runner that
+ * can't reread it refuses with `ActorUnavailable` rather than keep trusting
+ * keys the control plane may have removed. The provider's `refreshKeys` takes
+ * the edge's signed push and rereads the key set at once, however recently it
+ * was read, so a revoked key stops verifying without waiting for
+ * `refreshEvery`; repeating a push is harmless.
+ */
+export const assertion = (options) => {
+    const refreshMs = Duration.toMillis(Duration.fromInputUnsafe(options.refreshEvery ?? "5 minutes"));
+    const lock = Semaphore.makeUnsafe(1);
+    const source = options.keys;
+    let cached = source instanceof URL ? undefined : { keys: source.keys, at: Number.POSITIVE_INFINITY };
+    const fetchKeys = (url) => Effect.gen(function* () {
+        const client = HttpClient.filterStatusOk(yield* HttpClient.HttpClient);
+        const response = yield* client.get(url);
+        return (yield* decodeKeySet(yield* response.json)).keys;
+    }).pipe(Effect.mapError(() => ActorUnavailable.make({
+        cause: new Error("Actor.auth.assertion could not fetch its key set"),
+    })));
+    const keysFor = (unknownKid) => lock.withPermit(Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        if (source instanceof URL &&
+            (cached === undefined ||
+                now - cached.at >= refreshMs ||
+                (unknownKid && now - cached.at >= UNKNOWN_KID_REFRESH_MS)))
+            cached = { keys: yield* fetchKeys(source), at: now };
+        return cached.keys;
+    }));
+    /** The claims text of a JWS of type `decodeHeader` signed by a published, valid key. */
+    const signedClaims = Effect.fnUntraced(function* (token, decodeHeader) {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return yield* invalid;
+        const [encodedHeader, encodedClaims, encodedSignature] = parts;
+        const headerText = Base64Url.decodeString(encodedHeader);
+        const claimsText = Base64Url.decodeString(encodedClaims);
+        const signature = Base64Url.decode(encodedSignature);
+        if (Result.isFailure(headerText) || Result.isFailure(claimsText) || Result.isFailure(signature))
+            return yield* invalid;
+        const header = decodeHeader(headerText.success);
+        if (Option.isNone(header))
+            return yield* invalid;
+        const kid = header.value.kid;
+        const seconds = (yield* Clock.currentTimeMillis) / 1000;
+        const skew = ASSERTION_SKEW_MS / 1000;
+        const usable = (keys) => keys.find((key) => key.kid === kid &&
+            (key.nbf === undefined || key.nbf <= seconds + skew) &&
+            (key.exp === undefined || key.exp > seconds - skew));
+        const key = usable(yield* keysFor(false)) ?? usable(yield* keysFor(true));
+        if (key === undefined)
+            return yield* invalid;
+        if (!(yield* verifySignature(key, signature.success, `${encodedHeader}.${encodedClaims}`)))
+            return yield* invalid;
+        return claimsText.success;
+    });
+    /** Whether `iat` and `exp` give a lifetime within the cap, issued and unexpired within skew. */
+    const lifetime = Effect.fnUntraced(function* (claims) {
+        const seconds = (yield* Clock.currentTimeMillis) / 1000;
+        const skew = ASSERTION_SKEW_MS / 1000;
+        if (claims.exp <= claims.iat ||
+            claims.exp - claims.iat > MAX_ASSERTION_SECONDS ||
+            claims.iat > seconds + skew)
+            return yield* invalid;
+        if (claims.exp <= seconds - skew)
+            return yield* unauthorized("expired");
+    });
+    const authenticate = Effect.fnUntraced(function* (request) {
+        const claimsText = yield* signedClaims(yield* tokenOf(request), decodeAssertionHeader);
+        const claims = decodeClaims(claimsText);
+        if (Option.isNone(claims))
+            return yield* invalid;
+        const { iss, aud, region, iat, exp, tenant, caller, req, sid, cexp } = claims.value;
+        if (iss !== options.issuer || aud !== options.audience || region !== options.region)
+            return yield* invalid;
+        yield* lifetime({ iat, exp });
+        const binding = sid === undefined ? { request: req } : { request: req, session: sid };
+        const authenticated = { caller, tenant, binding };
+        if (cexp === undefined)
+            return authenticated;
+        const expiresAt = DateTime.make(cexp * 1000);
+        if (Option.isNone(expiresAt))
+            return yield* invalid;
+        return { ...authenticated, expiresAt: expiresAt.value };
+    });
+    const refreshKeys = Effect.fnUntraced(function* (request) {
+        const claims = decodeRefreshClaims(yield* signedClaims(yield* headerToken(request), decodeRefreshHeader));
+        if (Option.isNone(claims))
+            return yield* invalid;
+        if (claims.value.iss !== options.issuer || claims.value.aud !== options.audience)
+            return yield* invalid;
+        yield* lifetime(claims.value);
+        if (source instanceof URL)
+            yield* lock.withPermit(Effect.gen(function* () {
+                cached = { keys: yield* fetchKeys(source), at: yield* Clock.currentTimeMillis };
+            }));
+    });
+    return {
+        credentials: [Credential.Assertion()],
+        authenticate: authenticate,
+        refreshKeys: refreshKeys,
+    };
+};

package/dist/serve/auth.d.ts

@@ -0,0 +1,200 @@
+import { Data, type DateTime, Effect } from "effect";
+import { Headers } from "effect/http";
+import type { ActorUnavailable } from "../errors/actor.ts";
+import { Unauthorized } from "../errors/actor.ts";
+import { Anonymous, User } from "../identity/caller.ts";
+/** What a provider may read: headers, cookies when it asks for them, and a frame credential. Never the body. */
+export interface AuthRequest {
+    readonly headers: Headers.Headers;
+    /** Empty unless the provider accepts a cookie credential. */
+    readonly cookies: Readonly<Record<string, string>>;
+    /**
+     * A credential carried outside the headers, such as a WebSocket `hello`
+     * frame's `authorization`; it has the header's form, `Bearer <token>`.
+     */
+    readonly credential?: string;
+}
+/** What a provider resolves a request to: who is calling, in which tenant, and until when. */
+export interface Authenticated {
+    readonly caller: typeof User.Type | typeof Anonymous.Type;
+    readonly tenant: string;
+    /** The credential's own expiry, which caps live sessions. */
+    readonly expiresAt?: DateTime.Utc;
+    /**
+     * The one request the credential was issued for: the server refuses the
+     * request unless it rebuilds the same digest from what it received.
+     */
+    readonly binding?: Binding;
+}
+/** Ties a credential to one request, so a captured credential cannot be replayed on another. */
+export interface Binding {
+    /** The SHA-256 hex of the canonical request string. */
+    readonly request: string;
+    /** The streaming session the credential belongs to; a renewal must name the same one. */
+    readonly session?: string;
+}
+/** A credential a provider reads, documented as one OpenAPI security scheme. */
+export type Credential = Data.TaggedEnum<{
+    /** `authorization: Bearer <token>`. */
+    Bearer: {};
+    /** `authorization: Bearer <jwt>`, documented with `bearerFormat: JWT`. */
+    Jwt: {};
+    /** The named cookie. */
+    Cookie: {
+        readonly name: string;
+    };
+    /** `durable-assertion: <jws>`, a hosted edge's signed assertion. */
+    Assertion: {};
+}>;
+/** Constructors and matchers for `Credential`. */
+export declare const Credential: {
+    readonly $is: <Tag extends "Assertion" | "Bearer" | "Cookie" | "Jwt">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Assertion";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Bearer";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Cookie";
+        readonly name: string;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Jwt";
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "Assertion" | "Bearer" | "Cookie" | "Jwt"]: (args: Extract<{
+            readonly _tag: "Assertion";
+        } | {
+            readonly _tag: "Bearer";
+        } | {
+            readonly _tag: "Cookie";
+            readonly name: string;
+        } | {
+            readonly _tag: "Jwt";
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "Assertion";
+        } | {
+            readonly _tag: "Bearer";
+        } | {
+            readonly _tag: "Cookie";
+            readonly name: string;
+        } | {
+            readonly _tag: "Jwt";
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Assertion" | "Bearer" | "Cookie" | "Jwt"]>>;
+        <Cases extends { readonly [Tag in "Assertion" | "Bearer" | "Cookie" | "Jwt"]: (args: Extract<{
+            readonly _tag: "Assertion";
+        } | {
+            readonly _tag: "Bearer";
+        } | {
+            readonly _tag: "Cookie";
+            readonly name: string;
+        } | {
+            readonly _tag: "Jwt";
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "Assertion";
+        } | {
+            readonly _tag: "Bearer";
+        } | {
+            readonly _tag: "Cookie";
+            readonly name: string;
+        } | {
+            readonly _tag: "Jwt";
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Assertion" | "Bearer" | "Cookie" | "Jwt"]>>;
+    };
+    readonly Assertion: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Assertion";
+    }, "_tag">;
+    readonly Bearer: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Bearer";
+    }, "_tag">;
+    readonly Cookie: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Cookie";
+        readonly name: string;
+    }, "_tag">;
+    readonly Jwt: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Jwt";
+    }, "_tag">;
+};
+/** One way to authenticate every request an `Actor.serve` layer answers. */
+export interface AuthProvider<R = never> {
+    /**
+     * The credentials the provider accepts, any one of which authenticates a
+     * request; empty when it reads none. A `Cookie` entry is also what lets
+     * `authenticate` see the request's cookies.
+     */
+    readonly credentials: ReadonlyArray<Credential>;
+    readonly authenticate: (request: AuthRequest) => Effect.Effect<Authenticated, Unauthorized | ActorUnavailable, R>;
+    /**
+     * Rereads the provider's verification keys at once, for a request that
+     * proves it comes from the key issuer. A provider that has one is served
+     * a refresh route beside the protocol routes.
+     */
+    readonly refreshKeys?: (request: AuthRequest) => Effect.Effect<void, Unauthorized | ActorUnavailable, R>;
+}
+/** An `Unauthorized` failure with the given reason code. */
+export declare const unauthorized: (code: Unauthorized["code"]) => Unauthorized;
+/**
+ * The token of an `authorization: Bearer` header, or of the request's frame
+ * credential, which carries the same `Bearer <token>` value.
+ */
+export declare const bearerToken: (request: AuthRequest) => Effect.Effect<string, never, never> | Effect.Effect<never, Unauthorized, never>;
+/** Every request is `Anonymous` in the `"default"` tenant; any credential it carries is ignored. */
+export declare const none: AuthProvider;
+/** Verifies a request's credential; fails `Unauthorized` when it is missing, invalid, or expired. */
+type Authenticate<R> = (request: AuthRequest) => Effect.Effect<Authenticated, Unauthorized, R>;
+/**
+ * Options of a custom provider. It reads `authorization: Bearer` unless it
+ * names a cookie; one that reads both sets `bearer: true` as well.
+ */
+type MakeOptions<R> = {
+    readonly authenticate: Authenticate<R>;
+    readonly cookies?: undefined;
+    readonly bearer?: true;
+} | {
+    readonly authenticate: Authenticate<R>;
+    /** The cookie that carries the credential; the provider receives every request cookie. */
+    readonly cookies: {
+        readonly name: string;
+    };
+    readonly bearer?: boolean;
+};
+/**
+ * A custom provider: an `authenticate` function that reads a bearer token, or
+ * options naming a cookie. Throws when the cookie name is not an HTTP token.
+ *
+ * @example
+ * ```ts
+ * Actor.auth.make((request) =>
+ *   Effect.succeed({ caller: User.make({ subject: "ada" }), tenant: "acme" }),
+ * )
+ * ```
+ */
+export declare const make: <R = never>(provider: Authenticate<R> | MakeOptions<R>) => AuthProvider<R>;
+/** Whether the provider accepts a cookie credential, and so receives request cookies. */
+export declare const readsCookies: (provider: AuthProvider<unknown>) => boolean;
+/** Whether the tenant is a valid id and, for a `User`, its subject and encoded caller fit their byte limits. */
+export declare const withinLimits: (authenticated: Authenticated) => boolean;
+/** The default cap on the UTF-8 bytes of one credential a request carries. */
+export declare const CREDENTIAL_BYTES: number;
+/**
+ * Whether a credential `provider` would read from the request is over `limit`
+ * UTF-8 bytes: the `authorization` header or a frame credential, the cookie
+ * header for a cookie provider, and `durable-assertion` for an assertion
+ * provider. Checked before the provider runs, so it never parses an oversized one.
+ */
+export declare const oversizedCredential: (options: {
+    readonly provider: AuthProvider<unknown>;
+    readonly headers: Headers.Headers;
+    readonly limit: number;
+    readonly credential?: string | undefined;
+}) => boolean;
+export {};

package/dist/serve/auth.js

@@ -0,0 +1,92 @@
+import { Data, Effect, Option, Predicate, Schema } from "effect";
+import { Headers } from "effect/http";
+import { Unauthorized } from "../errors/actor.js";
+import { Anonymous, User } from "../identity/caller.js";
+import { ASSERTION_HEADER } from "./assertion/binding.js";
+/** Constructors and matchers for `Credential`. */
+export const Credential = Data.taggedEnum();
+/** An `Unauthorized` failure with the given reason code. */
+export const unauthorized = (code) => Unauthorized.make({ code });
+/**
+ * The token of an `authorization: Bearer` header, or of the request's frame
+ * credential, which carries the same `Bearer <token>` value.
+ */
+export const bearerToken = (request) => {
+    const header = request.credential === undefined
+        ? Headers.get(request.headers, "authorization")
+        : Option.some(request.credential);
+    if (Option.isNone(header))
+        return Effect.fail(unauthorized("missing_credentials"));
+    const match = /^Bearer[ ]+([^ ]+)[ ]*$/i.exec(header.value);
+    return match === null
+        ? Effect.fail(unauthorized("invalid_credentials"))
+        : Effect.succeed(match[1]);
+};
+/** Every request is `Anonymous` in the `"default"` tenant; any credential it carries is ignored. */
+export const none = {
+    credentials: [],
+    authenticate: () => Effect.succeed({ caller: Anonymous.make({}), tenant: "default" }),
+};
+/** RFC 6265's cookie-name, which is an RFC 9110 token. */
+const cookieName = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * A custom provider: an `authenticate` function that reads a bearer token, or
+ * options naming a cookie. Throws when the cookie name is not an HTTP token.
+ *
+ * @example
+ * ```ts
+ * Actor.auth.make((request) =>
+ *   Effect.succeed({ caller: User.make({ subject: "ada" }), tenant: "acme" }),
+ * )
+ * ```
+ */
+export const make = (provider) => {
+    if (Predicate.isFunction(provider))
+        return { credentials: [Credential.Bearer()], authenticate: provider };
+    if (provider.cookies === undefined)
+        return { credentials: [Credential.Bearer()], authenticate: provider.authenticate };
+    if (!cookieName.test(provider.cookies.name))
+        throw new Error(`Actor.auth.make: ${JSON.stringify(provider.cookies.name)} is not a cookie name`);
+    const cookie = Credential.Cookie({ name: provider.cookies.name });
+    return {
+        credentials: provider.bearer === true ? [Credential.Bearer(), cookie] : [cookie],
+        authenticate: provider.authenticate,
+    };
+};
+/** Whether the provider accepts a cookie credential, and so receives request cookies. */
+export const readsCookies = (provider) => provider.credentials.some(Credential.$is("Cookie"));
+const Tenant = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9._:-]{1,128}$/u));
+const isTenant = Schema.is(Tenant);
+const utf8 = new TextEncoder();
+/** Maximum UTF-8 bytes of a `User.subject`. */
+const SUBJECT_BYTES = 512;
+/** Maximum UTF-8 bytes of the JSON-encoded caller. */
+const CALLER_BYTES = 1024;
+/** Whether the tenant is a valid id and, for a `User`, its subject and encoded caller fit their byte limits. */
+export const withinLimits = (authenticated) => {
+    if (!isTenant(authenticated.tenant))
+        return false;
+    if (!Schema.is(User)(authenticated.caller))
+        return true;
+    const subject = utf8.encode(authenticated.caller.subject).byteLength;
+    return (subject >= 1 &&
+        subject <= SUBJECT_BYTES &&
+        utf8.encode(JSON.stringify(authenticated.caller)).byteLength <= CALLER_BYTES);
+};
+/** The default cap on the UTF-8 bytes of one credential a request carries. */
+export const CREDENTIAL_BYTES = 8 * 1024;
+/**
+ * Whether a credential `provider` would read from the request is over `limit`
+ * UTF-8 bytes: the `authorization` header or a frame credential, the cookie
+ * header for a cookie provider, and `durable-assertion` for an assertion
+ * provider. Checked before the provider runs, so it never parses an oversized one.
+ */
+export const oversizedCredential = (options) => {
+    const over = (value) => value !== undefined && utf8.encode(value).byteLength > options.limit;
+    const header = (name) => Option.getOrUndefined(Headers.get(options.headers, name));
+    return (over(options.credential) ||
+        over(header("authorization")) ||
+        (readsCookies(options.provider) && over(header("cookie"))) ||
+        (options.provider.credentials.some(Credential.$is("Assertion")) &&
+            over(header(ASSERTION_HEADER))));
+};

package/dist/serve/clock.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import { InternalActors } from "../runtime/actors.ts";
+/**
+ * The database clock without a database read per request: an offset from the
+ * monotonic clock, resampled every 10 seconds, keeping the sample with the
+ * shortest round trip, so the estimate is off by at most that round trip.
+ */
+export declare const databaseClock: Effect.Effect<{
+    now: () => number;
+}, never, InternalActors | import("effect/Scope").Scope>;

package/dist/serve/clock.js

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import { InternalActors } from "../runtime/actors.js";
+const SAMPLE_EVERY = "10 seconds";
+/** A sample older than this is replaced even if its round trip was shorter. */
+const STALE_MS = 60_000;
+/**
+ * The database clock without a database read per request: an offset from the
+ * monotonic clock, resampled every 10 seconds, keeping the sample with the
+ * shortest round trip, so the estimate is off by at most that round trip.
+ */
+export const databaseClock = Effect.gen(function* () {
+    const actors = yield* InternalActors;
+    const sample = Effect.gen(function* () {
+        const sent = performance.now();
+        const database = yield* actors.databaseNow;
+        const received = performance.now();
+        return { offset: database - (sent + received) / 2, rtt: received - sent, at: received };
+    });
+    let best = yield* sample.pipe(Effect.orDie);
+    yield* sample.pipe(Effect.delay(SAMPLE_EVERY), Effect.tap((next) => Effect.sync(() => {
+        if (next.rtt <= best.rtt || next.at - best.at >= STALE_MS)
+            best = next;
+    })), Effect.ignore, Effect.forever, Effect.forkScoped);
+    return { now: () => Math.round(performance.now() + best.offset) };
+});

package/dist/serve/jwt.d.ts

@@ -0,0 +1,65 @@
+import { Duration, Schema } from "effect";
+import { HttpClient } from "effect/http";
+import { type AuthProvider } from "./auth.ts";
+/** A JWS algorithm `Actor.auth.jwt` can verify. */
+type Algorithm = "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "EdDSA";
+/** A JSON Web Key as `Actor.auth.jwt` reads it; unrecognized members are dropped. */
+export declare const Jwk: Schema.Struct<{
+    readonly kty: Schema.String;
+    readonly kid: Schema.optionalKey<Schema.String>;
+    readonly alg: Schema.optionalKey<Schema.String>;
+    readonly use: Schema.optionalKey<Schema.String>;
+    readonly crv: Schema.optionalKey<Schema.String>;
+    readonly n: Schema.optionalKey<Schema.String>;
+    readonly e: Schema.optionalKey<Schema.String>;
+    readonly x: Schema.optionalKey<Schema.String>;
+    readonly y: Schema.optionalKey<Schema.String>;
+}>;
+/** A JSON Web Key as `Actor.auth.jwt` reads it. */
+export type Jwk = typeof Jwk.Type;
+/** A static JSON Web Key Set. */
+interface Jwks {
+    readonly keys: ReadonlyArray<Jwk>;
+}
+/** The verified payload of a JWT, handed to the `tenant` and `subject` callbacks. */
+type Claims = Readonly<Record<string, Schema.Json>>;
+/** Options of `Actor.auth.jwt`. */
+interface JwtOptions<Keys extends URL | Jwks> {
+    /** The required `iss` claim. */
+    readonly issuer: string;
+    /** The token's `aud` must include at least one of these. */
+    readonly audience: string | ReadonlyArray<string>;
+    /** A JWKS URL, fetched when first needed and refetched for an unknown `kid` at most once a minute, or static keys. */
+    readonly jwks: Keys;
+    /** The tenant, from verified claims only. A single-tenant application returns `"default"`. */
+    readonly tenant: (claims: Claims) => string;
+    /** The stable subject; defaults to the `sub` claim. */
+    readonly subject?: (claims: Claims) => string;
+    /** Accepted asymmetric algorithms. Default `RS256`, `ES256`, and `EdDSA`. */
+    readonly algorithms?: ReadonlyArray<Algorithm>;
+    /** Default 30 seconds. */
+    readonly clockTolerance?: Duration.Input;
+}
+/**
+ * Verifies `authorization: Bearer` JWTs signed with an asymmetric key. `exp`
+ * is required; `iss` must equal `issuer` and `aud` must name an `audience`;
+ * `nbf` and `exp` are checked within `clockTolerance`. Tokens with `crit`
+ * headers or an algorithm outside `algorithms` are refused. A missing
+ * `authorization` header fails `missing_credentials`, an expired token
+ * `expired`, and every other failure `invalid_credentials`. With a JWKS URL
+ * the provider needs an `HttpClient`, and an unreachable key set fails
+ * `ActorUnavailable`.
+ * The credential's `exp` becomes the session's `expiresAt`.
+ *
+ * @example
+ * ```ts
+ * Actor.auth.jwt({
+ *   issuer: "https://issuer.example.com",
+ *   audience: "my-api",
+ *   jwks: new URL("https://issuer.example.com/.well-known/jwks.json"),
+ *   tenant: () => "default",
+ * })
+ * ```
+ */
+export declare const jwt: <Keys extends URL | Jwks>(options: JwtOptions<Keys>) => AuthProvider<Keys extends URL ? HttpClient.HttpClient : never>;
+export {};