@we8/cloudflare 0.1.2 → 0.2.0

package/README.md

@@ -1,7 +1,12 @@
 # @we8/cloudflare
 
-The Cloudflare pack for a we8 CMS project. Three things, and only three:
+The Cloudflare pack for a we8 CMS project. Four things, and only four:
 
+- **Two admin auth providers**, for sites that do not want a user table.
+  `cloudflareAccessAdminAuth()` validates the assertion a Cloudflare Access
+  application forwards; `perimeterAdminAuth({ acknowledged: true })` checks
+  nothing at all, because something in front of the worker already did. See
+  [Admin auth](#admin-auth) below.
 - **A real email sender.** `cloudflareEmailSender` plugs into the CMS email
   seam and sends over Cloudflare Email Service. It is off until a site sets
   `EMAIL_MODE=cloudflare`, binds `send_email` as `EMAIL`, and sets
@@ -9,13 +14,16 @@ The Cloudflare pack for a we8 CMS project. Three things, and only three:
   behaviour, so installing the pack never changes how a site works. Sending
   never throws: mail from a CMS is always a side effect of something that
   already succeeded.
-- **The wrangler config generator.** `generateWranglerConfig(answers)` returns
-  the `wrangler.jsonc` a project deploys with, shaped after the CMS package's
-  own config. `create-we8` writes a new project's config with it.
+- **Two generators.** `generateWranglerConfig(answers)` returns the
+  `wrangler.jsonc` a project deploys with, shaped after the CMS package's own
+  config. `generateSkill({ mode, site })` returns the project skill an agentic
+  tool loads, written for the auth mode the project is actually in.
+  `create-we8` writes both into a new project.
 - **The `we8-cloudflare` CLI.** `doctor` says what is missing and the exact
   command that fixes it; `migrate` applies the migrations that ship inside
-  `@we8/cms`; `seed` loads the development seed into the local database and
-  refuses, always, to touch a deployed one.
+  `@we8/cms` and then every installed provider's; `seed` loads the development
+  seed into the local database and refuses, always, to touch a deployed one;
+  `skill` writes or refreshes the project skill in place.
 
 ```
 npx @we8/cloudflare doctor            # what is missing, and how to fix it
@@ -23,8 +31,29 @@ npx @we8/cloudflare doctor --remote   # the same, including deployed secrets
 npx @we8/cloudflare migrate           # apply migrations locally
 npx @we8/cloudflare migrate --remote  # apply them to the deployed database
 npx @we8/cloudflare seed              # local development data, local only
+npx @we8/cloudflare skill             # write .claude/skills/we8/SKILL.md
+npx @we8/cloudflare skill --check     # exit 1 if it is missing or stale
 ```
 
+## The project skill
+
+`skill` writes `.claude/skills/we8/SKILL.md`, the operating manual an agentic
+coding tool loads when it opens the project: the composition, the commands,
+the auth model with its own mode's guardrails, the key model, the API, AEO,
+and the standing guardrails. `create-we8` writes it at scaffold time; this
+command is how a project that predates it adopts one, and how a project whose
+auth registration changed refreshes it.
+
+Nothing is asked for. The mode is read out of the worker entry with its
+comments stripped, the site workspace is a directory that either exists or
+does not, and a perimeter registration that has not acknowledged itself is
+reported as such. A directory that is not a we8 project is refused rather than
+written a skill that would be a guess.
+
+`--check` writes nothing and exits 1 when the file is missing or out of date,
+which is what belongs in CI. `doctor` warns, and never fails, when the file is
+absent.
+
 ## Requirements
 
 - Peer dependencies, declared and auto-installed by npm: `@we8/cms` (the
@@ -33,6 +62,70 @@ npx @we8/cloudflare seed              # local development data, local only
 - Node 20 or newer.
 - A Cloudflare account only when you deploy; local development runs entirely
   offline.
+- For `cloudflareAccessAdminAuth`: a Cloudflare Zero Trust account with an
+  Access application in front of this Worker's hostname. Nothing else; the
+  provider has no dependencies of its own and verifies on WebCrypto.
+
+## Admin auth
+
+`@we8/cms` has no admin auth of its own. A worker that registers no provider
+refuses every `/v1/admin/*` request, which is the secure default; `@we8/auth`
+is the embedded provider most self-hosters want, and these two are for the
+sites that do not want a user table at all.
+
+### Cloudflare Access
+
+```ts
+import cms, { registerAdminAuth } from '@we8/cms';
+import { cloudflareAccessAdminAuth } from '@we8/cloudflare';
+
+registerAdminAuth(cloudflareAccessAdminAuth());
+
+export default cms;
+```
+
+Put an Access application in front of the Worker's hostname, and Cloudflare
+does the signing in: the policy decides who reaches the worker, and every
+request it forwards carries a signed assertion naming the person. This
+provider verifies that assertion against the team's published keys, for this
+application's audience, from this team's issuer, and inside its own expiry,
+before it becomes an identity. Being behind Access is not what it trusts, so a
+request that arrives by another route carrying a copied, forged, or expired
+token is refused exactly like one carrying none.
+
+Four vars configure it, none of them secret:
+
+| Var | Required | What it is |
+| --- | --- | --- |
+| `ACCESS_TEAM_DOMAIN` | yes | `acme`, `acme.cloudflareaccess.com`, or the full URL |
+| `ACCESS_AUD` | yes | The Access application's Application Audience tag |
+| `ACCESS_OWNER_EMAILS` | one of the two | The addresses that hold the owner role, comma-separated |
+| `ACCESS_OWNER_DEFAULT` | one of the two | `true` makes every identity Access admits an owner |
+
+Any of them may be passed to `cloudflareAccessAdminAuth({ ... })` instead;
+what is passed wins, and what is left out is read from the environment.
+Everyone Access admits who is not named an owner is a member, which is the
+CMS's editorial role. `GET /v1/auth/mode` reports `external` with sign-up
+closed: the site's accounts are not this worker's to create.
+
+### Perimeter mode
+
+```ts
+registerAdminAuth(perimeterAdminAuth({ acknowledged: true }));
+```
+
+Every request that reaches `/v1/admin/*` is the owner. There is nothing else
+to it, and that is both the point and the risk: if the perimeter ever opens (a
+policy edited, a hostname exposed, the `workers.dev` route left enabled), the
+whole admin API opens with it, the form inbox and its personal data included.
+It is the right answer behind a VPN, a company gateway, or an Access
+application with no role mapping to give this worker, and the wrong answer
+everywhere else.
+
+`acknowledged: true` is how a project says it read that paragraph.
+`we8-cloudflare doctor` warns about perimeter mode always and
+`doctor --remote` fails a deployment that has not acknowledged it.
+
 ## The guardrail
 
 `seed/local.sql` contains plaintext API keys, because that is what a

package/dist/access.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The Cloudflare Access admin auth provider.
+ *
+ * Put the admin behind a Cloudflare Access application and Cloudflare does the
+ * signing in: the policy decides who reaches the worker at all, and every
+ * request it lets through carries a signed assertion naming the person. This
+ * provider validates that assertion and turns it into the identity the CMS
+ * gates on, so a site gets a real admin login with no user table, no password
+ * to reset, and no session for this worker to sign.
+ *
+ *     import cms, { registerAdminAuth } from '@we8/cms';
+ *     import { cloudflareAccessAdminAuth } from '@we8/cloudflare';
+ *
+ *     registerAdminAuth(cloudflareAccessAdminAuth());
+ *     export default cms;
+ *
+ * Being behind Access is NOT what this trusts. The assertion is verified
+ * against the team's published keys, for this application's audience, and
+ * within its own expiry, so a request that reaches the worker by another route
+ * carrying a copied, forged, or expired token is refused exactly like one
+ * carrying none. See jwt.ts for the verification itself.
+ *
+ * It claims no routes and offers no first-account flow: `GET /v1/auth/mode`
+ * reports `external` with sign-up closed, because the site's accounts are not
+ * this worker's to create.
+ */
+import type { AdminAuthProvider, UserRole } from './admin-auth.js';
+/** What `GET /v1/auth/mode` reports this provider as. */
+export declare const ACCESS_PROVIDER_NAME = "cloudflare-access";
+/** The header Cloudflare Access adds to every request it forwards. */
+export declare const ACCESS_JWT_HEADER = "Cf-Access-Jwt-Assertion";
+/** The cookie Access also sets, read only when the header is absent. */
+export declare const ACCESS_JWT_COOKIE = "CF_Authorization";
+/**
+ * What this provider needs to know. Every field may instead be a var on the
+ * worker, which is where the scaffolder puts them: a config value given here
+ * wins, and anything left out is read from the environment at request time.
+ *
+ * The environment is the default because none of these are secrets (a team
+ * domain is public and an AUD tag identifies an application rather than
+ * authorising anything), because `wrangler.jsonc` is where a project's
+ * configuration already lives, and because the doctor can then check them.
+ */
+export interface CloudflareAccessConfig {
+    /**
+     * The Access team domain. `acme`, `acme.cloudflareaccess.com`, and
+     * `https://acme.cloudflareaccess.com` are all accepted and mean the same
+     * thing. It gives both the JWKS URL and the issuer.
+     */
+    teamDomain?: string;
+    /** The Access application's AUD tag, from its configuration page. */
+    audience?: string;
+    /** The emails that hold the owner role. Everyone else Access admits is a member. */
+    owners?: readonly string[];
+    /**
+     * Every identity Access admits is an owner. For the solo operator whose
+     * Access policy already names exactly one person, where an owners list would
+     * be the same name written twice.
+     */
+    ownerByDefault?: boolean;
+}
+/** The vars this provider reads when the config leaves a value out. */
+export interface CloudflareAccessEnv {
+    ACCESS_TEAM_DOMAIN?: string | undefined;
+    ACCESS_AUD?: string | undefined;
+    /** Comma-separated. Whitespace around an address is ignored. */
+    ACCESS_OWNER_EMAILS?: string | undefined;
+    /** `true` makes every admitted identity an owner. */
+    ACCESS_OWNER_DEFAULT?: string | undefined;
+}
+/**
+ * `acme`, `acme.cloudflareaccess.com`, and a full URL all become
+ * `acme.cloudflareaccess.com`, so the issuer and the JWKS URL are built from
+ * one normalized value however the operator wrote it down.
+ */
+export declare function normalizeTeamDomain(input: string): string;
+/** Where the team publishes the public half of its signing keys. */
+export declare function accessCertsUrl(teamDomain: string): string;
+/** The `iss` every assertion from this team carries. */
+export declare function accessIssuer(teamDomain: string): string;
+/** The resolved settings one request is validated against. */
+export interface AccessSettings {
+    teamDomain: string;
+    certsUrl: string;
+    issuer: string;
+    audience: string;
+    owners: string[];
+    ownerByDefault: boolean;
+}
+/**
+ * Merges the config and the environment into the settings a request is checked
+ * against, or says what is missing. A placeholder left in `wrangler.jsonc`
+ * counts as missing: it is what the scaffolder writes when nobody has filled
+ * the value in yet, and treating it as a real team domain would only turn a
+ * clear "not configured" into a confusing "does not verify".
+ */
+export declare function resolveAccessSettings(config: CloudflareAccessConfig, env: unknown): {
+    ok: true;
+    settings: AccessSettings;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The assertion on a request: the header Access adds, or the cookie it sets
+ * when something reached the worker without it. Null when neither is present,
+ * which the CMS turns into a plain 401.
+ */
+export declare function readAssertion(request: Request): string | null;
+/**
+ * Owner when the address is on the list (or the site says every identity
+ * owns it), member otherwise. Least privilege: an address nobody named gets
+ * the editorial role, never the administrative one.
+ */
+export declare function accessRole(email: string, settings: AccessSettings): UserRole;
+/** Forgets what has already been logged. Tests use it; the request path does not. */
+export declare function clearAccessReports(): void;
+/**
+ * The provider, ready to register.
+ *
+ * Everything it cannot do, it refuses. An absent assertion, a token that does
+ * not verify, an identity with no email claim (an Access service token, for
+ * instance, which is a machine and not an administrator), and a configuration
+ * this worker cannot make sense of all resolve to null, which the CMS answers
+ * as a 401. The public API is untouched either way: only the admin surface
+ * depends on any of this.
+ */
+export declare function cloudflareAccessAdminAuth(config?: CloudflareAccessConfig): AdminAuthProvider;
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAiB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAUlF,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,qDAAqD;IACrD,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;CACzB;AAgBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,OAAO,GACX;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA6CxE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAc7D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,QAAQ,CAG5E;AAeD,qFAAqF;AACrF,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,GAAE,sBAA2B,GAClC,iBAAiB,CAuCnB"}

package/dist/access.js

@@ -0,0 +1,211 @@
+/**
+ * The Cloudflare Access admin auth provider.
+ *
+ * Put the admin behind a Cloudflare Access application and Cloudflare does the
+ * signing in: the policy decides who reaches the worker at all, and every
+ * request it lets through carries a signed assertion naming the person. This
+ * provider validates that assertion and turns it into the identity the CMS
+ * gates on, so a site gets a real admin login with no user table, no password
+ * to reset, and no session for this worker to sign.
+ *
+ *     import cms, { registerAdminAuth } from '@we8/cms';
+ *     import { cloudflareAccessAdminAuth } from '@we8/cloudflare';
+ *
+ *     registerAdminAuth(cloudflareAccessAdminAuth());
+ *     export default cms;
+ *
+ * Being behind Access is NOT what this trusts. The assertion is verified
+ * against the team's published keys, for this application's audience, and
+ * within its own expiry, so a request that reaches the worker by another route
+ * carrying a copied, forged, or expired token is refused exactly like one
+ * carrying none. See jwt.ts for the verification itself.
+ *
+ * It claims no routes and offers no first-account flow: `GET /v1/auth/mode`
+ * reports `external` with sign-up closed, because the site's accounts are not
+ * this worker's to create.
+ */
+import { verifyAccessJwt } from './jwt.js';
+import { ACCESS_AUD_VAR, ACCESS_OWNER_DEFAULT_VAR, ACCESS_OWNER_EMAILS_VAR, ACCESS_TEAM_DOMAIN_VAR, isPlaceholder, } from './wrangler-config.js';
+/** What `GET /v1/auth/mode` reports this provider as. */
+export const ACCESS_PROVIDER_NAME = 'cloudflare-access';
+/** The header Cloudflare Access adds to every request it forwards. */
+export const ACCESS_JWT_HEADER = 'Cf-Access-Jwt-Assertion';
+/** The cookie Access also sets, read only when the header is absent. */
+export const ACCESS_JWT_COOKIE = 'CF_Authorization';
+/**
+ * `acme`, `acme.cloudflareaccess.com`, and a full URL all become
+ * `acme.cloudflareaccess.com`, so the issuer and the JWKS URL are built from
+ * one normalized value however the operator wrote it down.
+ */
+export function normalizeTeamDomain(input) {
+    let value = input.trim().toLowerCase();
+    value = value.replace(/^https?:\/\//, '');
+    value = value.replace(/\/.*$/, '');
+    if (value.length === 0)
+        return '';
+    return value.endsWith('.cloudflareaccess.com') ? value : `${value}.cloudflareaccess.com`;
+}
+/** Where the team publishes the public half of its signing keys. */
+export function accessCertsUrl(teamDomain) {
+    return `https://${normalizeTeamDomain(teamDomain)}/cdn-cgi/access/certs`;
+}
+/** The `iss` every assertion from this team carries. */
+export function accessIssuer(teamDomain) {
+    return `https://${normalizeTeamDomain(teamDomain)}`;
+}
+function parseOwners(value) {
+    if (!value)
+        return [];
+    return value
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0 && !isPlaceholder(entry));
+}
+function configured(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 || isPlaceholder(trimmed) ? undefined : trimmed;
+}
+/**
+ * Merges the config and the environment into the settings a request is checked
+ * against, or says what is missing. A placeholder left in `wrangler.jsonc`
+ * counts as missing: it is what the scaffolder writes when nobody has filled
+ * the value in yet, and treating it as a real team domain would only turn a
+ * clear "not configured" into a confusing "does not verify".
+ */
+export function resolveAccessSettings(config, env) {
+    const bindings = (typeof env === 'object' && env !== null ? env : {});
+    const teamDomain = configured(config.teamDomain) ?? configured(bindings.ACCESS_TEAM_DOMAIN);
+    if (!teamDomain) {
+        return {
+            ok: false,
+            reason: `no team domain: pass teamDomain to cloudflareAccessAdminAuth, or set vars.${ACCESS_TEAM_DOMAIN_VAR}`,
+        };
+    }
+    const audience = configured(config.audience) ?? configured(bindings.ACCESS_AUD);
+    if (!audience) {
+        return {
+            ok: false,
+            reason: `no audience: pass audience to cloudflareAccessAdminAuth, or set vars.${ACCESS_AUD_VAR}`,
+        };
+    }
+    const owners = config.owners !== undefined
+        ? config.owners.map((entry) => entry.trim().toLowerCase()).filter((entry) => entry.length > 0)
+        : parseOwners(bindings.ACCESS_OWNER_EMAILS);
+    const ownerByDefault = config.ownerByDefault ?? bindings.ACCESS_OWNER_DEFAULT?.trim().toLowerCase() === 'true';
+    if (owners.length === 0 && !ownerByDefault) {
+        return {
+            ok: false,
+            reason: `nobody would be an owner: set vars.${ACCESS_OWNER_EMAILS_VAR} to the owner addresses, or vars.${ACCESS_OWNER_DEFAULT_VAR} to "true" if every identity Access admits should own this site`,
+        };
+    }
+    return {
+        ok: true,
+        settings: {
+            teamDomain: normalizeTeamDomain(teamDomain),
+            certsUrl: accessCertsUrl(teamDomain),
+            issuer: accessIssuer(teamDomain),
+            audience,
+            owners,
+            ownerByDefault,
+        },
+    };
+}
+/**
+ * The assertion on a request: the header Access adds, or the cookie it sets
+ * when something reached the worker without it. Null when neither is present,
+ * which the CMS turns into a plain 401.
+ */
+export function readAssertion(request) {
+    const header = request.headers.get(ACCESS_JWT_HEADER);
+    if (header && header.trim().length > 0)
+        return header.trim();
+    const cookies = request.headers.get('Cookie');
+    if (!cookies)
+        return null;
+    for (const part of cookies.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq <= 0)
+            continue;
+        if (part.slice(0, eq).trim() !== ACCESS_JWT_COOKIE)
+            continue;
+        const value = part.slice(eq + 1).trim();
+        if (value.length > 0)
+            return value;
+    }
+    return null;
+}
+/**
+ * Owner when the address is on the list (or the site says every identity
+ * owns it), member otherwise. Least privilege: an address nobody named gets
+ * the editorial role, never the administrative one.
+ */
+export function accessRole(email, settings) {
+    if (settings.ownerByDefault)
+        return 'owner';
+    return settings.owners.includes(email.trim().toLowerCase()) ? 'owner' : 'member';
+}
+/**
+ * Logged once per distinct reason per isolate. A misconfiguration is the same
+ * on every request, and repeating it once per request would bury the rest of
+ * the log without telling the operator anything new.
+ */
+const reported = new Set();
+function reportOnce(message) {
+    if (reported.has(message))
+        return;
+    reported.add(message);
+    console.error(`[access] ${message}`);
+}
+/** Forgets what has already been logged. Tests use it; the request path does not. */
+export function clearAccessReports() {
+    reported.clear();
+}
+/**
+ * The provider, ready to register.
+ *
+ * Everything it cannot do, it refuses. An absent assertion, a token that does
+ * not verify, an identity with no email claim (an Access service token, for
+ * instance, which is a machine and not an administrator), and a configuration
+ * this worker cannot make sense of all resolve to null, which the CMS answers
+ * as a 401. The public API is untouched either way: only the admin surface
+ * depends on any of this.
+ */
+export function cloudflareAccessAdminAuth(config = {}) {
+    return {
+        name: ACCESS_PROVIDER_NAME,
+        async resolve(request, env) {
+            const resolved = resolveAccessSettings(config, env);
+            if (!resolved.ok) {
+                reportOnce(`${resolved.reason}; the admin API is refused until it is`);
+                return null;
+            }
+            const token = readAssertion(request);
+            if (!token)
+                return null;
+            const verification = await verifyAccessJwt({
+                token,
+                certsUrl: resolved.settings.certsUrl,
+                issuer: resolved.settings.issuer,
+                audience: resolved.settings.audience,
+            });
+            if (!verification.ok) {
+                console.warn(`[access] refused an assertion: ${verification.reason}`);
+                return null;
+            }
+            const email = verification.claims.email;
+            if (typeof email !== 'string' || email.length === 0) {
+                console.warn('[access] the assertion carries no email claim, so it names no administrator');
+                return null;
+            }
+            const sub = verification.claims.sub;
+            return {
+                userId: typeof sub === 'string' && sub.length > 0 ? sub : email.toLowerCase(),
+                email,
+                role: accessRole(email, resolved.settings),
+            };
+        },
+    };
+}
+//# sourceMappingURL=access.js.map

package/dist/access.js.map

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

package/dist/admin-auth.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The admin auth seam, restated.
+ *
+ * These four declarations mirror `AdminIdentity`, `AdminAuthProvider`,
+ * `FirstRunState`, and `UserRole` in `@we8/cms`. They are restated here for the
+ * same reason `EmailSender` is (see email.ts): the pack declares the CMS as a
+ * peer rather than a dependency, so the two packages typecheck and build in
+ * any order, and neither has to exist before the other. The interfaces are
+ * structural, so a provider shaped like this one satisfies the CMS's seam
+ * wherever a composed worker registers it, and the generated project's own
+ * `npm run typecheck` is what proves the two still line up.
+ *
+ * The division of labour the CMS documents holds here too: a provider says WHO
+ * a request is, and the core decides WHAT that identity may do. Nothing in this
+ * file, and nothing in either provider beside it, has an opinion about the
+ * owner and member semantics; those live in `@we8/cms` and stay there.
+ */
+/** The two roles the CMS knows. Mirrors `UserRole` in `@we8/cms`. */
+export type UserRole = 'owner' | 'member';
+/**
+ * Who a provider says this request is. `email` is optional because not every
+ * identity source has one; it is what publish history is attributed to.
+ */
+export interface AdminIdentity {
+    userId: string;
+    role: UserRole;
+    email?: string | null;
+}
+/** Whether a provider still offers a way to create the very first account. */
+export type FirstRunState = 'open' | 'closed';
+/** Mirrors `AdminAuthProvider` in `@we8/cms`. */
+export interface AdminAuthProvider {
+    /** What `GET /v1/auth/mode` reports the provider as. */
+    name: string;
+    /** Resolves the request to an identity, or null when it carries none. */
+    resolve(request: Request, env: unknown): Promise<AdminIdentity | null>;
+    /** Claims routes of the provider's own. Neither provider here claims any. */
+    handleRoute?(request: Request, env: unknown): Promise<Response | null>;
+    /** Whether a first-account flow is available. Neither provider here has one. */
+    firstRun?(env: unknown): Promise<FirstRunState>;
+}
+//# sourceMappingURL=admin-auth.d.ts.map

package/dist/admin-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-auth.d.ts","sourceRoot":"","sources":["../src/admin-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9C,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACvE,6EAA6E;IAC7E,WAAW,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACvE,gFAAgF;IAChF,QAAQ,CAAC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACjD"}

package/dist/admin-auth.js

@@ -0,0 +1,19 @@
+/**
+ * The admin auth seam, restated.
+ *
+ * These four declarations mirror `AdminIdentity`, `AdminAuthProvider`,
+ * `FirstRunState`, and `UserRole` in `@we8/cms`. They are restated here for the
+ * same reason `EmailSender` is (see email.ts): the pack declares the CMS as a
+ * peer rather than a dependency, so the two packages typecheck and build in
+ * any order, and neither has to exist before the other. The interfaces are
+ * structural, so a provider shaped like this one satisfies the CMS's seam
+ * wherever a composed worker registers it, and the generated project's own
+ * `npm run typecheck` is what proves the two still line up.
+ *
+ * The division of labour the CMS documents holds here too: a provider says WHO
+ * a request is, and the core decides WHAT that identity may do. Nothing in this
+ * file, and nothing in either provider beside it, has an opinion about the
+ * owner and member semantics; those live in `@we8/cms` and stay there.
+ */
+export {};
+//# sourceMappingURL=admin-auth.js.map

package/dist/admin-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-auth.js","sourceRoot":"","sources":["../src/admin-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/cli-args.d.ts

@@ -2,17 +2,23 @@
  * Argument parsing for `we8-cloudflare`, kept apart from the CLI that spawns
  * wrangler so the shapes below can be tested without a subprocess.
  */
-export type CommandName = 'doctor' | 'migrate' | 'seed' | 'help' | 'version';
+export type CommandName = 'doctor' | 'migrate' | 'seed' | 'skill' | 'help' | 'version';
 export interface ParsedCommand {
     command: CommandName;
     /** Where the project lives. Defaults to the working directory. */
     dir: string;
     /** True when the command should act on the deployed database. */
     remote: boolean;
+    /**
+     * `skill --check`: report instead of writing, and exit non-zero when the
+     * file is missing or out of date. One flag rather than two spellings, so a
+     * CI step and a doctor's fix line name the same thing.
+     */
+    check: boolean;
     /** Set when the arguments cannot be honoured. The CLI prints it and exits 1. */
     error?: string;
 }
-export declare const USAGE = "we8-cloudflare - the Cloudflare pack for a we8 CMS project\n\nUsage:\n  we8-cloudflare doctor [--remote] [--dir <path>]\n      Check the project's configuration and print what is missing, with the\n      command that fixes each thing. --remote also checks the deployed\n      Worker's secrets.\n\n  we8-cloudflare migrate [--remote] [--dir <path>]\n      Apply the @we8/cms migrations in order. Local by default; --remote\n      applies them to the deployed D1 database.\n\n  we8-cloudflare seed [--dir <path>]\n      Load the development seed into the LOCAL database. It contains plaintext\n      API keys, so this command has no remote mode and refuses to be given one.\n\n  we8-cloudflare help | --version\n";
+export declare const USAGE = "we8-cloudflare - the Cloudflare pack for a we8 CMS project\n\nUsage:\n  we8-cloudflare doctor [--remote] [--dir <path>]\n      Check the project's configuration and print what is missing, with the\n      command that fixes each thing. --remote also checks the deployed\n      Worker's secrets.\n\n  we8-cloudflare migrate [--remote] [--dir <path>]\n      Apply the @we8/cms migrations in order, then the migrations of every\n      installed provider package (today: @we8/auth). Local by default;\n      --remote applies them to the deployed D1 database.\n\n  we8-cloudflare seed [--dir <path>]\n      Load the development seed into the LOCAL database. It contains plaintext\n      API keys, so this command has no remote mode and refuses to be given one.\n\n  we8-cloudflare skill [--check] [--dir <path>]\n      Write .claude/skills/we8/SKILL.md, the operating manual an agentic tool\n      loads when it opens this project, generated from the project's own auth\n      mode and workspace. --check writes nothing and exits 1 when the file is\n      missing or out of date, which is what belongs in CI.\n\n  we8-cloudflare help | --version\n";
 /**
  * Parses argv (without the node and script entries). Unknown flags are an
  * error rather than a silent no-op, because a typo in `--remote` on a migrate

package/dist/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,KAAK,2sBAiBjB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAoDhF"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEvF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,KAAK,0nCAwBjB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAsEhF"}