@runlot/auth 0.1.0-rc.100

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import { type User } from "./index.js";
+export interface NextOpts {
+    next?: string;
+}
+/** The social providers a project can register (docs/auth.md §9). */
+export type AuthProvider = "github" | "google" | "kakao";
+/** The sign-in page. Given a provider, it goes straight to that provider's
+ *  authorize. */
+export declare function signInUrl(provider?: AuthProvider, opts?: NextOpts): string;
+/**
+ * The sign-up page.
+ *
+ * **There is no provider argument.** For social logins, signing up and signing
+ * in are one path (docs/auth.md §5 — there is only `GET sign-in/{provider}`,
+ * and the identity upsert rides the linking rules of §6), so a URL like
+ * `signUpUrl("github")` does not exist on the server. To sign somebody up with
+ * a social provider, use `signInUrl(provider)`.
+ */
+export declare function signUpUrl(opts?: NextOpts): string;
+/**
+ * Sign-out.
+ *
+ * **It is a POST target, not a link** (docs/auth.md §5). Use it as `<form
+ * method="post" action={signOutUrl()}>` — if a GET could sign somebody out, a
+ * single `<img>` embedded in somebody else's page could throw the user out.
+ */
+export declare function signOutUrl(opts?: NextOpts): string;
+/**
+ * Who is signed in right now. This is what a client-rendered app calls while
+ * booting.
+ *
+ * Anything other than a 200 gives `{ user: null }` — being signed out is an
+ * answer, not an exception (a 401 is an answer too), and throwing would turn
+ * every page into a try/catch.
+ *
+ * `fetchImpl` is the hole through which the tests inject a fake.
+ */
+export declare function session(fetchImpl?: typeof fetch): Promise<{
+    user: User | null;
+}>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qEAAqE;AACrE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAsBzD;iBACiB;AACjB,wBAAgB,SAAS,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAE1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAElD;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,CAAC,CAKtF"}

package/dist/client.js

@@ -0,0 +1,70 @@
+// Browser helpers (docs/auth.md §10). Building links and one `GET /session` is
+// all there is, so it has zero dependencies, and it does not claim to know
+// again what the server already knows.
+import { AUTH_BASE } from "./index.js";
+// `next` lets through only a same-origin relative path — the same rule as
+// `safeNext` in docs/auth.md §5. It has to start with `/` and must not start
+// with `//`: the browser reads `//evil.example` as an absolute URL, which makes
+// it an open redirect.
+//
+// Filtering here is a convenience, not a security boundary. A link can also be
+// made by hand, so the server runs the same check again.
+function safeNext(next) {
+    if (next === undefined || next === "")
+        return null;
+    if (!next.startsWith("/"))
+        return null;
+    if (next.startsWith("//"))
+        return null;
+    return next;
+}
+function authUrl(path, provider, opts) {
+    const base = `${AUTH_BASE}/${path}${provider ? `/${provider}` : ""}`;
+    const next = safeNext(opts?.next);
+    return next === null ? base : `${base}?next=${encodeURIComponent(next)}`;
+}
+/** The sign-in page. Given a provider, it goes straight to that provider's
+ *  authorize. */
+export function signInUrl(provider, opts) {
+    return authUrl("sign-in", provider, opts);
+}
+/**
+ * The sign-up page.
+ *
+ * **There is no provider argument.** For social logins, signing up and signing
+ * in are one path (docs/auth.md §5 — there is only `GET sign-in/{provider}`,
+ * and the identity upsert rides the linking rules of §6), so a URL like
+ * `signUpUrl("github")` does not exist on the server. To sign somebody up with
+ * a social provider, use `signInUrl(provider)`.
+ */
+export function signUpUrl(opts) {
+    return authUrl("sign-up", undefined, opts);
+}
+/**
+ * Sign-out.
+ *
+ * **It is a POST target, not a link** (docs/auth.md §5). Use it as `<form
+ * method="post" action={signOutUrl()}>` — if a GET could sign somebody out, a
+ * single `<img>` embedded in somebody else's page could throw the user out.
+ */
+export function signOutUrl(opts) {
+    return authUrl("sign-out", undefined, opts);
+}
+/**
+ * Who is signed in right now. This is what a client-rendered app calls while
+ * booting.
+ *
+ * Anything other than a 200 gives `{ user: null }` — being signed out is an
+ * answer, not an exception (a 401 is an answer too), and throwing would turn
+ * every page into a try/catch.
+ *
+ * `fetchImpl` is the hole through which the tests inject a fake.
+ */
+export async function session(fetchImpl) {
+    const f = fetchImpl ?? fetch;
+    const res = await f(`${AUTH_BASE}/session`, { credentials: "same-origin" });
+    if (!res.ok)
+        return { user: null };
+    return (await res.json());
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,uCAAuC;AAEvC,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AASlD,0EAA0E;AAC1E,6EAA6E;AAC7E,gFAAgF;AAChF,uBAAuB;AACvB,EAAE;AACF,+EAA+E;AAC/E,yDAAyD;AACzD,SAAS,QAAQ,CAAC,IAAwB;IACxC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACnD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,OAAO,CAAC,IAAY,EAAE,QAAuB,EAAE,IAAe;IACrE,MAAM,IAAI,GAAG,GAAG,SAAS,IAAI,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACrE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,SAAS,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED;iBACiB;AACjB,MAAM,UAAU,SAAS,CAAC,QAAuB,EAAE,IAAe;IAChE,OAAO,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe;IACvC,OAAO,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAAe;IACxC,OAAO,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,SAAwB;IACpD,MAAM,CAAC,GAAG,SAAS,IAAI,KAAK,CAAC;IAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,SAAS,UAAU,EAAE,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC,CAAC;IAC5E,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACnC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAC;AACrD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+/** The path prefix the system worker terminates (docs/auth.md §5). */
+export declare const AUTH_BASE = "/__runlot/auth";
+export interface User {
+    /** uuid — the PK of `runlot_auth.users` and the value RLS looks at. */
+    id: string;
+    email: string | null;
+    emailVerified: boolean;
+    name: string | null;
+    avatarUrl: string | null;
+    /** The sign-in methods linked to this user. For example:
+     *  `["password", "github"]`. */
+    providers: string[];
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601. `null` if they have never signed in. */
+    lastSignInAt: string | null;
+}
+/**
+ * The one deletion-cookie line `signOut` returns. Used as a `HeadersInit` as
+ * is.
+ */
+export interface SignOutHeaders {
+    "set-cookie": string;
+}
+/** One page of `users.list`. A `null` `cursor` means it is the last page. */
+export interface UserPage {
+    users: User[];
+    cursor: string | null;
+}
+export interface UserUpdate {
+    name?: string | null;
+    avatarUrl?: string | null;
+    /** `true` also revokes every session of that user (docs/auth.md §4). */
+    banned?: boolean;
+}
+/** Administrative reads and writes. They do not go through the gateway; they
+ *  read directly through the `DB` binding. */
+export interface AuthUsers {
+    get(id: string): Promise<User | null>;
+    getByEmail(email: string): Promise<User | null>;
+    list(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<UserPage>;
+    update(id: string, patch: UserUpdate): Promise<User>;
+    /** The user, the identities, the sessions and the tokens. The app's own
+     *  tables are joined up by the app with `ON DELETE`. */
+    delete(id: string): Promise<void>;
+}
+export interface AuthSessions {
+    /** The idiom after a password change. */
+    revokeAll(userId: string): Promise<void>;
+}
+export interface AuthBinding {
+    /**
+     * Cookie → session → user. `null` when there is none.
+     * **It does not throw** — not being signed in is not an error.
+     */
+    user(request: Request): Promise<User | null>;
+    /**
+     * Erases that session and returns the deletion cookie. Putting it on the
+     * response is the caller's job.
+     *
+     * ```ts
+     * return new Response(null, { headers: await env.auth.signOut(request) });
+     * ```
+     *
+     * It is a plain object rather than a `Headers` because of a measurement —
+     * `Headers` cannot cross the RPC boundary (docs/auth.md §4). It is still a
+     * `HeadersInit`, so it goes on exactly as above.
+     */
+    signOut(request: Request): Promise<SignOutHeaders>;
+    users: AuthUsers;
+    sessions: AuthSessions;
+    getUser?(id: string): Promise<User | null>;
+    getUserByEmail?(email: string): Promise<User | null>;
+    listUsers?(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<UserPage>;
+    updateUser?(id: string, patch: UserUpdate): Promise<User>;
+    deleteUser?(id: string): Promise<void>;
+    revokeSessions?(userId: string): Promise<void>;
+}
+/**
+ * The fragment to attach to your own `Env`.
+ *
+ * ```ts
+ * interface Env extends AuthEnv {
+ *   db: Fetcher;
+ * }
+ * ```
+ */
+export interface AuthEnv {
+    auth: AuthBinding;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,17 @@
+// The types for `env.auth` (docs/auth.md §4, §10).
+//
+// This package ships no runtime. The binding is injected by the auth system
+// worker inside workerd, so all a user gets from npm is the type to attach to
+// their own `Env` and the helpers called from the browser
+// (`@runlot/auth/client`). That is also why it has zero dependencies — it must
+// not add a single byte to the worker bundle.
+//
+// `user(request)` taking a request is a constraint, not a taste (the same
+// argument as docs/access.md §4.2): `env` is a bundle fixed for the lifetime of
+// the worker, and the identity is a different value on every request. The
+// argument-free shape only holds inside round 6's Next.js adapter, which hides
+// the request in `AsyncLocalStorage`; anywhere else it is a `TypeError` — if
+// "cannot be done" quietly became `null`, every page would look logged out.
+/** The path prefix the system worker terminates (docs/auth.md §5). */
+export const AUTH_BASE = "/__runlot/auth";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,0DAA0D;AAC1D,+EAA+E;AAC/E,8CAA8C;AAC9C,EAAE;AACF,0EAA0E;AAC1E,gFAAgF;AAChF,0EAA0E;AAC1E,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAE5E,sEAAsE;AACtE,MAAM,CAAC,MAAM,SAAS,GAAG,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@runlot/auth",
+  "version": "0.1.0-rc.100",
+  "description": "Types and browser helpers for env.auth — Runlot provides the runtime",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runlot/runlot",
+    "directory": "web/packages/auth"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "esbuild": "^0.24.2",
+    "typescript": "^5.7.2",
+    "@runlot/config": "0.1.0-rc.100"
+  },
+  "scripts": {
+    "test": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}