@rikalabs/akter 0.1.0-alpha.0

package/dist/serve/jwt.js

@@ -0,0 +1,202 @@
+import { Clock, DateTime, Duration, Effect, Option, Result, Schema, Semaphore } from "effect";
+import { Base64Url } from "effect/encoding";
+import { HttpClient } from "effect/http";
+import { ActorUnavailable } from "../errors/actor.js";
+import { User } from "../identity/caller.js";
+import { bearerToken, Credential, unauthorized } from "./auth.js";
+/** A JSON Web Key as `Actor.auth.jwt` reads it; unrecognized members are dropped. */
+export const Jwk = Schema.Struct({
+    kty: Schema.String,
+    kid: Schema.optionalKey(Schema.String),
+    alg: Schema.optionalKey(Schema.String),
+    use: Schema.optionalKey(Schema.String),
+    crv: Schema.optionalKey(Schema.String),
+    n: Schema.optionalKey(Schema.String),
+    e: Schema.optionalKey(Schema.String),
+    x: Schema.optionalKey(Schema.String),
+    y: Schema.optionalKey(Schema.String),
+});
+const JwksJson = Schema.Struct({ keys: Schema.Array(Schema.Unknown) });
+const decodeJwk = Schema.decodeUnknownOption(Jwk);
+const rsa = (name, bits) => ({
+    kty: "RSA",
+    importKey: { name, hash: `SHA-${bits}` },
+    verify: name === "RSA-PSS" ? { name, saltLength: bits / 8 } : { name },
+});
+const ALGORITHMS = {
+    RS256: rsa("RSASSA-PKCS1-v1_5", 256),
+    RS384: rsa("RSASSA-PKCS1-v1_5", 384),
+    RS512: rsa("RSASSA-PKCS1-v1_5", 512),
+    PS256: rsa("RSA-PSS", 256),
+    PS384: rsa("RSA-PSS", 384),
+    PS512: rsa("RSA-PSS", 512),
+    ES256: {
+        kty: "EC",
+        crv: "P-256",
+        importKey: { name: "ECDSA", namedCurve: "P-256" },
+        verify: { name: "ECDSA", hash: "SHA-256" },
+    },
+    ES384: {
+        kty: "EC",
+        crv: "P-384",
+        importKey: { name: "ECDSA", namedCurve: "P-384" },
+        verify: { name: "ECDSA", hash: "SHA-384" },
+    },
+    EdDSA: {
+        kty: "OKP",
+        crv: "Ed25519",
+        importKey: { name: "Ed25519" },
+        verify: { name: "Ed25519" },
+    },
+};
+const isAlgorithm = Schema.is(Schema.Literals(Object.keys(ALGORITHMS)));
+const Header = Schema.Struct({
+    alg: Schema.String,
+    kid: Schema.optionalKey(Schema.String),
+    crit: Schema.optionalKey(Schema.Unknown),
+});
+const decodeHeader = Schema.decodeUnknownOption(Schema.fromJsonString(Header));
+const decodeClaims = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Record(Schema.String, Schema.Json)));
+const isNumber = Schema.is(Schema.Finite);
+const isString = Schema.is(Schema.String);
+const REFRESH_MS = 60_000;
+const invalid = unauthorized("invalid_credentials");
+const fits = (jwk, alg) => {
+    const params = ALGORITHMS[alg];
+    return (jwk.kty === params.kty &&
+        (params.crv === undefined || jwk.crv === params.crv) &&
+        (jwk.alg === undefined || jwk.alg === alg) &&
+        (jwk.use === undefined || jwk.use === "sig"));
+};
+const utf8 = new TextEncoder();
+const verifySignature = Effect.fnUntraced(function* (jwk, alg, signature, signed) {
+    const params = ALGORITHMS[alg];
+    const key = yield* Effect.tryPromise({
+        try: () => crypto.subtle.importKey("jwk", jwk, params.importKey, false, ["verify"]),
+        catch: () => invalid,
+    });
+    return yield* Effect.tryPromise({
+        try: () => crypto.subtle.verify(params.verify, key, new Uint8Array(signature), utf8.encode(signed)),
+        catch: () => invalid,
+    });
+});
+/**
+ * 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 const jwt = (options) => {
+    const algorithms = new Set(options.algorithms ?? ["RS256", "ES256", "EdDSA"]);
+    for (const alg of algorithms)
+        if (!isAlgorithm(alg))
+            throw new Error(`Actor.auth.jwt: unsupported algorithm ${String(alg)}`);
+    const audiences = new Set(isString(options.audience) ? [options.audience] : options.audience);
+    const toleranceMs = Duration.toMillis(Duration.fromInputUnsafe(options.clockTolerance ?? "30 seconds"));
+    const lock = Semaphore.makeUnsafe(1);
+    const source = options.jwks;
+    let cached;
+    if (!(source instanceof URL))
+        cached = { 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);
+        const body = yield* Schema.decodeUnknownEffect(JwksJson)(yield* response.json);
+        const keys = [];
+        for (const raw of body.keys) {
+            const jwk = decodeJwk(raw);
+            if (Option.isSome(jwk))
+                keys.push(jwk.value);
+        }
+        return keys;
+    }).pipe(Effect.mapError(() => ActorUnavailable.make({ cause: new Error("Actor.auth.jwt could not fetch its JWKS") })));
+    const keysFor = (refresh) => lock.withPermit(Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        if (source instanceof URL &&
+            (cached === undefined || (refresh && now - cached.at >= REFRESH_MS)))
+            cached = { keys: yield* fetchKeys(source), at: now };
+        return cached.keys;
+    }));
+    const authenticate = Effect.fnUntraced(function* (request) {
+        const token = yield* bearerToken(request);
+        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) || header.value.crit !== undefined)
+            return yield* invalid;
+        const alg = header.value.alg;
+        if (!isAlgorithm(alg) || !algorithms.has(alg))
+            return yield* invalid;
+        const kid = header.value.kid;
+        const signed = `${encodedHeader}.${encodedClaims}`;
+        const candidates = (keys) => keys.filter((jwk) => fits(jwk, alg) && (kid === undefined || jwk.kid === kid));
+        let keys = candidates(yield* keysFor(false));
+        if (keys.length === 0 && kid !== undefined)
+            keys = candidates(yield* keysFor(true));
+        let verified = false;
+        for (const jwk of keys)
+            if (yield* verifySignature(jwk, alg, signature.success, signed)) {
+                verified = true;
+                break;
+            }
+        if (!verified)
+            return yield* invalid;
+        const claims = decodeClaims(claimsText.success);
+        if (Option.isNone(claims))
+            return yield* invalid;
+        const { exp, nbf, iss, aud, sub } = claims.value;
+        if (!isNumber(exp) || iss !== options.issuer)
+            return yield* invalid;
+        const audience = isString(aud) ? [aud] : Array.isArray(aud) ? aud : [];
+        if (!audience.some((value) => isString(value) && audiences.has(value)))
+            return yield* invalid;
+        const now = yield* Clock.currentTimeMillis;
+        if (nbf !== undefined && (!isNumber(nbf) || nbf * 1000 > now + toleranceMs))
+            return yield* invalid;
+        if (exp * 1000 <= now - toleranceMs)
+            return yield* unauthorized("expired");
+        const expiresAt = DateTime.make(exp * 1000);
+        if (Option.isNone(expiresAt))
+            return yield* invalid;
+        const resolved = yield* Effect.try({
+            try: () => ({
+                subject: options.subject === undefined ? sub : options.subject(claims.value),
+                tenant: options.tenant(claims.value),
+            }),
+            catch: () => invalid,
+        });
+        if (!isString(resolved.subject) || resolved.subject === "" || !isString(resolved.tenant))
+            return yield* invalid;
+        return {
+            caller: User.make({ subject: resolved.subject }),
+            tenant: resolved.tenant,
+            expiresAt: expiresAt.value,
+        };
+    });
+    return {
+        credentials: [Credential.Jwt()],
+        authenticate: authenticate,
+    };
+};

package/dist/serve/layer.d.ts

@@ -0,0 +1,98 @@
+import { HttpRouter } from "effect/http";
+import { InternalActors } from "../runtime/actors.ts";
+import { RuntimeControl } from "../runtime/drain.ts";
+import { type AuthProvider } from "./auth.ts";
+import type { AnyFleetView } from "../tables/fleet.ts";
+/** Options of `Actor.serve`; `R` is what `auth` needs from the environment. */
+export interface ServeOptions<R> {
+    /** Actor definitions to serve; their layers are provided as usual. */
+    readonly actors: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    /** Authenticates every request this layer answers. Required: `Actor.auth.none` is the explicit public opt-out. */
+    readonly auth: AuthProvider<R>;
+    /** Prefix for every route, such as `"/api"`. */
+    readonly basePath?: `/${string}`;
+    /** Serves the OpenAPI 3.1 document at `path`; off unless given. */
+    readonly openapi?: {
+        readonly path: `/${string}`;
+        readonly title?: string;
+        readonly version?: string;
+    };
+    /**
+     * Serves an MCP endpoint at `path`, derived from the same OpenAPI document:
+     * every public command, reducer, and query is a tool, and each call is
+     * authenticated and authorized like its HTTP route. Off unless given.
+     */
+    readonly mcp?: {
+        readonly path: `/${string}`;
+        readonly name?: string;
+        readonly version?: string;
+    };
+    /**
+     * Fleet views to serve at `GET /fleet/{View}` as server-sent events, for
+     * the caller's own tenant; each must be registered with the runtime's
+     * `fleet` option.
+     */
+    readonly fleet?: ReadonlyArray<AnyFleetView>;
+    /** Browser origins allowed besides the server's own. Requests without `Origin` are always served. */
+    readonly origins?: ReadonlyArray<string>;
+    /** Size limits; each falls back to its default. */
+    readonly limits?: {
+        /** Largest request body in bytes. Default 1 MiB. */
+        readonly requestBytes?: number;
+        /** Largest `authorization`, `cookie` or assertion header, and frame credential, in bytes. Default 8 KiB. */
+        readonly credentialBytes?: number;
+        /**
+         * The body limit of `POST /content`, the one route exempt from
+         * `requestBytes`. Default and maximum 64 MiB, the content size limit.
+         */
+        readonly contentBytes?: number;
+    };
+}
+export { isSameOrigin } from "./origin.ts";
+/**
+ * Serves `actors`' public commands, reducers, queries, streams, connections,
+ * event feeds, and content over HTTP by adding routes to the `HttpRouter`,
+ * plus `/protocol`, `/command-ids`, `/ready`, and, when configured, the
+ * OpenAPI document. Building the layer dies when an actor is listed twice, a
+ * member collides with a protocol route, the runtime's retry window is under
+ * 60 seconds, an actor's layers are not provided, `limits.contentBytes` is out
+ * of range, or the auth provider declares two credentials of one OpenAPI
+ * scheme (the document names one scheme per kind, so the second would vanish).
+ *
+ * Guarantees and ordering:
+ * - Every route checks the origin before authenticating, then the protocol
+ *   version.
+ * - A credential bound to a request admits only that request, checked before
+ *   any turn; a renewal binds the session's upgrade path and its own session id.
+ * - A malformed `durable-min-version` is refused, because ignoring it would
+ *   silently drop the caller's read-your-writes guarantee.
+ * - A command accepted for execution continues if the client disconnects: the
+ *   runtime owns its execution and only the caller's wait is interrupted.
+ * - A request with neither `content-length` nor `transfer-encoding` may carry
+ *   no body stream at all, and is read as empty.
+ * - A connection is a WebSocket upgrade; nothing is authorized or woken before
+ *   its `hello`. A non-browser client, or a cookie provider, may authenticate
+ *   the upgrade request itself.
+ * - An event feed authorizes every tag the caller reads (there is no
+ *   wildcard), answers cursor errors before any stream starts, and never
+ *   creates the actor it follows. A browser's reconnect resumes from
+ *   `Last-Event-ID`.
+ * - A content upload streams into the store hashed as it arrives; past the
+ *   limit its transaction rolls back and nothing is stored. Under a credential
+ *   bound to its request it is read whole first, up to the same limit, so the
+ *   binding is checked before anything is stored. A sweep between
+ *   resolving a download's name and reading its bytes ends the body before any
+ *   byte, short of its declared length.
+ * - `/ready` carries no credentials and is never cached, because a stale
+ *   answer would route traffic to a draining runner.
+ * - With a provider that has `refreshKeys`, the edge's push after it revokes a
+ *   signing key rereads the key set at once.
+ *
+ * @example
+ * ```ts
+ * const Api = Actor.serve({ actors: [Counter], auth: Actor.auth.none, basePath: "/api" })
+ * ```
+ */
+export declare const serve: <R = never>(options: ServeOptions<R>) => import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter | InternalActors | RuntimeControl | Exclude<R, import("effect/Scope").Scope>>;