@aikagi/runtime 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @aikagi/runtime
+
+Load your [aikagi](https://aikagi.dev) keys into a running app at start-up. Nothing is copied into your hosting provider.
+
+- **Vercel**: uses the deployment's OIDC token. No key is stored on Vercel.
+- **Cloudflare Workers / Pages**: uses one read-only key (`AIKAGI_KEY`) that `aikagi init` puts there for you.
+
+Values are fetched once per instance and kept in memory. If aikagi cannot be reached, start-up fails instead of running with missing values.
+
+## Set up
+
+In your repository, run `aikagi init`. It finds `.vercel/project.json` or your `wrangler` config and connects the project.
+
+## Next.js on Vercel
+
+```ts
+// instrumentation.ts
+import { loadAikagi } from '@aikagi/runtime'
+
+export async function register() {
+  await loadAikagi()
+}
+```
+
+## Cloudflare Workers
+
+```ts
+import { withAikagi } from '@aikagi/runtime'
+
+export default withAikagi({
+  async fetch(request, env) {
+    return new Response(env.DATABASE_URL ? 'ok' : 'missing')
+  },
+})
+```
+
+Every fetch shows up in the project's access history in aikagi.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 実行中のアプリが、起動時に aikagi から値を取る。
+ *
+ * - Vercel（Next.js など）: `instrumentation.ts` の `register()` で `await loadAikagi()`。
+ *   デプロイが持つ OIDC トークンを使うので、Vercel に鍵は置かない。
+ * - Cloudflare Workers: `export default withAikagi({ fetch(request, env) { ... } })`。
+ *   `aikagi init` が置いた `AIKAGI_KEY`（読み取りだけの鍵）を使う。
+ *
+ * どちらも 1 つのインスタンス（isolate）の中では 1 回だけ取りに行き、あとはメモリの値を使う。
+ * aikagi に届かなければ起動（最初の要求）が失敗する。黙って空のまま動かさない。
+ *
+ * 依存は無い（fetch だけ）。値はログにもエラーの文言にも出さない。
+ */
+export declare const DEFAULT_API_URL = "https://app.aikagi.dev";
+/** Cloudflare に置く鍵の名前（`aikagi init` がこの名前で置く）。 */
+export declare const KEY_BINDING = "AIKAGI_KEY";
+export interface LoadOptions {
+    /** aikagi の API。既定は `AIKAGI_API_URL`、無ければ https://app.aikagi.dev。 */
+    apiUrl?: string;
+    /** 同じ Vercel プロジェクトを複数の aikagi プロジェクトが信頼しているときだけ要る。 */
+    workspace?: string;
+    project?: string;
+    /**
+     * 実行時の鍵。既定は `AIKAGI_KEY`。渡すと Vercel の OIDC ではなくこちらを使う。
+     */
+    key?: string;
+    /** Vercel の OIDC トークン。既定は要求の `x-vercel-oidc-token`、無ければ `VERCEL_OIDC_TOKEN`。 */
+    vercelOidcToken?: string;
+    /** テスト用。 */
+    fetch?: typeof fetch;
+}
+export declare class AikagiError extends Error {
+    readonly status: number | null;
+    constructor(message: string, status?: number | null);
+}
+type Vars = Record<string, string | undefined>;
+/** 資格を交換し、その環境の値を取る。キャッシュはしない（呼ぶ側が持つ）。 */
+export declare function fetchAikagi(options?: LoadOptions, vars?: Vars): Promise<Record<string, string>>;
+/**
+ * Node.js（Vercel の関数、Next.js）で使う。値を取り、`process.env` に入れる。
+ * 1 つのインスタンスで 2 回目からはメモリの値を返す（取り直さない）。
+ * 失敗したら次の呼び出しでもう一度取りに行く。
+ */
+export declare function loadAikagi(options?: LoadOptions): Promise<Record<string, string>>;
+/** テスト用。インスタンスのキャッシュを捨てる。 */
+export declare function resetAikagiCache(): void;
+/**
+ * Cloudflare Workers / Pages Functions の `env` に aikagi の値を足したものを返す。
+ * 鍵ごとに isolate の中で 1 回だけ取りに行く。
+ */
+export declare function aikagiEnv<E extends object>(env: E, options?: LoadOptions): Promise<E & Record<string, string>>;
+type Handler = Record<string, unknown>;
+/**
+ * モジュール形式の Worker を包む。`fetch` / `scheduled` / `queue` などの第 2 引数（env）に
+ * aikagi の値を足してから元の関数を呼ぶ。
+ */
+export declare function withAikagi<H extends Handler>(handler: H, options?: LoadOptions): H;
+export {};

package/dist/index.js

@@ -0,0 +1,153 @@
+/**
+ * 実行中のアプリが、起動時に aikagi から値を取る。
+ *
+ * - Vercel（Next.js など）: `instrumentation.ts` の `register()` で `await loadAikagi()`。
+ *   デプロイが持つ OIDC トークンを使うので、Vercel に鍵は置かない。
+ * - Cloudflare Workers: `export default withAikagi({ fetch(request, env) { ... } })`。
+ *   `aikagi init` が置いた `AIKAGI_KEY`（読み取りだけの鍵）を使う。
+ *
+ * どちらも 1 つのインスタンス（isolate）の中では 1 回だけ取りに行き、あとはメモリの値を使う。
+ * aikagi に届かなければ起動（最初の要求）が失敗する。黙って空のまま動かさない。
+ *
+ * 依存は無い（fetch だけ）。値はログにもエラーの文言にも出さない。
+ */
+export const DEFAULT_API_URL = 'https://app.aikagi.dev';
+/** Cloudflare に置く鍵の名前（`aikagi init` がこの名前で置く）。 */
+export const KEY_BINDING = 'AIKAGI_KEY';
+export class AikagiError extends Error {
+    status;
+    constructor(message, status = null) {
+        super(message);
+        this.name = 'AikagiError';
+        this.status = status;
+    }
+}
+function processEnv() {
+    const proc = globalThis.process;
+    return proc?.env ?? {};
+}
+/**
+ * Vercel が要求ごとに渡す OIDC トークン（`@vercel/oidc` と同じ探し方）。
+ * 要求の外（起動時）では `VERCEL_OIDC_TOKEN` を読む。
+ */
+function vercelOidcToken(vars) {
+    const context = globalThis[Symbol.for('@vercel/request-context')];
+    const fromRequest = context?.get?.()?.headers?.['x-vercel-oidc-token'];
+    return fromRequest || vars.VERCEL_OIDC_TOKEN || undefined;
+}
+async function post(fetchImpl, url, body, token) {
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'user-agent': 'aikagi-runtime',
+                ...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch {
+        throw new AikagiError(`aikagi: could not reach ${new URL(url).origin}`);
+    }
+    if (!res.ok) {
+        // 本文のうち、文言と手がかりだけを出す（値は入っていない）。
+        let detail = '';
+        try {
+            const parsed = (await res.json());
+            detail = [parsed.error?.message, parsed.error?.hint].filter(Boolean).join(' — ');
+        }
+        catch {
+            // 本文が JSON でなければ番号だけ。
+        }
+        throw new AikagiError(`aikagi: ${new URL(url).pathname} returned ${res.status}${detail ? `: ${detail}` : ''}`, res.status);
+    }
+    return (await res.json());
+}
+/** 資格を交換し、その環境の値を取る。キャッシュはしない（呼ぶ側が持つ）。 */
+export async function fetchAikagi(options = {}, vars = processEnv()) {
+    const fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+    const apiUrl = (options.apiUrl ?? vars.AIKAGI_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, '');
+    const key = options.key ?? vars[KEY_BINDING];
+    let exchanged;
+    if (key) {
+        exchanged = await post(fetchImpl, `${apiUrl}/api/auth/runtime-key`, { key });
+    }
+    else {
+        const token = options.vercelOidcToken ?? vercelOidcToken(vars);
+        if (!token) {
+            throw new AikagiError(`aikagi: no credential found; on Vercel turn on OIDC for the project, on Cloudflare run \`aikagi init\` to set ${KEY_BINDING}`);
+        }
+        exchanged = await post(fetchImpl, `${apiUrl}/api/auth/vercel-oidc`, {
+            token,
+            ...(options.workspace === undefined ? {} : { workspace: options.workspace }),
+            ...(options.project === undefined ? {} : { project: options.project }),
+        });
+    }
+    const resolved = await post(fetchImpl, `${apiUrl}/api/runtime/resolve`, {
+        workspace: exchanged.workspace,
+        project: exchanged.project,
+        environment: exchanged.environment,
+        // 監査の resolve 行に「どこから取ったか」を残す。
+        command: key ? 'runtime-key' : 'vercel',
+    }, exchanged.access_token);
+    return resolved.env;
+}
+let loaded = null;
+/**
+ * Node.js（Vercel の関数、Next.js）で使う。値を取り、`process.env` に入れる。
+ * 1 つのインスタンスで 2 回目からはメモリの値を返す（取り直さない）。
+ * 失敗したら次の呼び出しでもう一度取りに行く。
+ */
+export function loadAikagi(options = {}) {
+    if (loaded === null) {
+        const env = processEnv();
+        loaded = fetchAikagi(options, env).then((values) => {
+            // aikagi の値を正とする（前に先方へ置いた古い値があっても上書きする）。
+            Object.assign(env, values);
+            return values;
+        }, (err) => {
+            loaded = null;
+            throw err;
+        });
+    }
+    return loaded;
+}
+/** テスト用。インスタンスのキャッシュを捨てる。 */
+export function resetAikagiCache() {
+    loaded = null;
+    workerCache.clear();
+}
+const workerCache = new Map();
+/**
+ * Cloudflare Workers / Pages Functions の `env` に aikagi の値を足したものを返す。
+ * 鍵ごとに isolate の中で 1 回だけ取りに行く。
+ */
+export function aikagiEnv(env, options = {}) {
+    const vars = env;
+    const key = options.key ?? vars[KEY_BINDING];
+    if (!key) {
+        return Promise.reject(new AikagiError(`aikagi: ${KEY_BINDING} is not set; run \`aikagi init\` in the repository`));
+    }
+    let pending = workerCache.get(key);
+    if (pending === undefined) {
+        pending = fetchAikagi({ ...options, key }, vars);
+        workerCache.set(key, pending);
+        pending.catch(() => workerCache.delete(key));
+    }
+    return pending.then((values) => ({ ...env, ...values }));
+}
+/**
+ * モジュール形式の Worker を包む。`fetch` / `scheduled` / `queue` などの第 2 引数（env）に
+ * aikagi の値を足してから元の関数を呼ぶ。
+ */
+export function withAikagi(handler, options = {}) {
+    const wrapped = { ...handler };
+    for (const [name, value] of Object.entries(handler)) {
+        if (typeof value !== 'function')
+            continue;
+        wrapped[name] = async (first, env, ...rest) => value.call(handler, first, await aikagiEnv(env, options), ...rest);
+    }
+    return wrapped;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@aikagi/runtime",
+  "version": "0.1.0",
+  "description": "Load your aikagi keys into a running app at start-up (Vercel via OIDC, Cloudflare Workers via one read-only key).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dx-proj/aikagi.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://aikagi.dev/guide/ci/",
+  "keywords": [
+    "aikagi",
+    "secrets",
+    "environment-variables",
+    "vercel",
+    "cloudflare-workers",
+    "oidc"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}