@tempoxyz/example-id-cli 0.0.0-stage → 0.0.0

package/dist/Session.js

@@ -0,0 +1,100 @@
+/**
+ * The CLI's saved sign-in: the user, their tokens, and the CLI's access key, in a file only the
+ * current user can read. `TEMPO_ID_CREDENTIALS` moves the file.
+ * @module
+ */
+import * as Fs from 'node:fs/promises';
+import * as Os from 'node:os';
+import * as Path from 'node:path';
+import { Key } from '@tempoxyz/id/client';
+import { app, client } from './viem.config.js';
+/** Where the sign-in is saved. */
+const file = process.env.TEMPO_ID_CREDENTIALS ??
+    Path.join(Os.homedir(), '.config', 'tempo-id-playground', 'credentials.json');
+/**
+ * Returns the saved sign-in, refreshing its access token when it is expired, and sets the client's
+ * account to its key. Returns `undefined` when signed out. A sign-in saved by an older CLI, whose
+ * key is expired or for another chain, or that another deployment or app issued counts as signed out, so its tokens
+ * never reach the deployment that `TEMPO_ID_URL` names, and `login` authorizes a new key.
+ */
+export async function get() {
+    const saved = await Fs.readFile(file, 'utf8')
+        .then((text) => JSON.parse(text))
+        .catch(() => undefined);
+    // Earlier CLIs saved no `user`, or kept the tokens under `tokens`, so those count as signed out.
+    if (saved?.url !== new URL(app.url).origin ||
+        saved.clientId !== app.clientId ||
+        !saved.user ||
+        !saved.key?.keyAuthorization ||
+        // A key for another chain, such as one saved with another `TEMPO_RPC_URL`, cannot send here.
+        Number(saved.key.chainId) !== client.chain.id ||
+        !saved.accessToken ||
+        Key.expired(saved.key))
+        return undefined;
+    client.auth.restore(saved);
+    if (saved.expiresAt - 30_000 > Date.now())
+        return saved;
+    const tokens = await client.auth
+        .refresh({ refreshToken: saved.refreshToken })
+        .catch(() => undefined);
+    if (!tokens)
+        return undefined;
+    return save({ ...saved, ...tokens });
+}
+/**
+ * Revokes the saved refresh token at the revocation endpoint (RFC 7009) of the deployment that
+ * issued it, and forgets the sign-in. Returns whether the revocation succeeded. A failed one still
+ * forgets the sign-in.
+ */
+export async function remove() {
+    const saved = await read();
+    const revoked = saved?.refreshToken ? await revoke(saved) : true;
+    await Fs.rm(file, { force: true });
+    return revoked;
+}
+/** Returns the saved sign-in as the file holds it, or `undefined` without a readable one. */
+export async function read() {
+    return await Fs.readFile(file, 'utf8')
+        .then((text) => JSON.parse(text))
+        .catch(() => undefined);
+}
+/**
+ * Revokes the refresh token of `session` at the revocation endpoint (RFC 7009) of the deployment
+ * that issued it, and returns whether the revocation succeeded.
+ */
+export async function revoke(session) {
+    // A sign-in saved by an older CLI names no deployment to revoke it at.
+    if (!session.refreshToken || !session.url || !session.clientId)
+        return false;
+    const response = await fetch(new URL('/oauth2/revoke', session.url), {
+        body: new URLSearchParams({
+            client_id: session.clientId,
+            token: session.refreshToken,
+            token_type_hint: 'refresh_token',
+        }),
+        method: 'POST',
+        signal: AbortSignal.timeout(10_000),
+    }).catch(() => undefined);
+    await response?.body?.cancel();
+    return response?.ok ?? false;
+}
+/**
+ * Saves a sign-in, readable only by the current user. The sign-in replaces the saved one in one
+ * rename, so a failed write leaves the earlier sign-in as it was.
+ */
+export async function save(session) {
+    await Fs.mkdir(Path.dirname(file), { recursive: true });
+    const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+    try {
+        await Fs.writeFile(temporary, JSON.stringify(session), {
+            flag: 'wx',
+            mode: 0o600,
+        });
+        await Fs.rename(temporary, file);
+    }
+    catch (error) {
+        await Fs.rm(temporary, { force: true });
+        throw error;
+    }
+    return session;
+}

package/dist/commands/fund.js

@@ -0,0 +1,17 @@
+/** Funds the user's Tempo Account from the Tempo testnet faucet, including OUSD for fees. @module */
+import { Cli } from 'incur';
+import * as Session from '../Session.js';
+import { client } from '../viem.config.js';
+export default Cli.command({
+    description: 'Fund your Tempo Account with testnet tokens',
+    async run(c) {
+        const session = await Session.get();
+        if (!session)
+            return c.error({
+                code: 'SIGNED_OUT',
+                message: 'Not signed in. Run `login`.',
+            });
+        await client.faucet.fundSync({ account: client.account.address });
+        return { account: session.key.account, funded: true };
+    },
+});

package/dist/commands/login.js

@@ -0,0 +1,133 @@
+/**
+ * Signs in: shows a code to approve in any browser, waits for approval, and saves the tokens with
+ * the CLI's new access key and its authorization.
+ * @module
+ */
+import { Permissions } from '@tempoxyz/id/client';
+import { Cli, z } from 'incur';
+import { Json, Value } from 'ox';
+import { Expiry, Scopes } from 'viem/tempo';
+import { tempoLocalnet, tempoTestnet } from 'viem/tempo/chains';
+import * as Tokens from 'viem/tokens';
+import * as Session from '../Session.js';
+import { app, client, ousd } from '../viem.config.js';
+export default Cli.command({
+    description: 'Sign in by approving a code in any browser',
+    options: z.object({
+        expiry: z
+            .string()
+            .regex(/^\d+[smhdw]?$/)
+            .optional()
+            .describe('How long the key lasts, such as 30m, 12h, 7d, or 2w, or a Unix time'),
+        limit: z
+            .array(z
+            .string()
+            .regex(/^\d+(\.\d+)?:[^:,/]+(\/\d+[smhdw]?)?(,\d+(\.\d+)?:[^:,/]+(\/\d+[smhdw]?)?)*$/))
+            .optional()
+            .describe('Spending limits, such as 100:OUSD, 100:OUSD/1d to reset daily, or 100:OUSD,50:EURC.e. Repeat or comma-separate for more'),
+        scope: z
+            .array(z.string().regex(/^\w+:[^:,]+(,\w+:[^:,]+)*$/))
+            .optional()
+            .describe('Token calls the key may make, such as transfer:OUSD,approve:OUSD. Repeat or comma-separate for more'),
+    }),
+    async *run(c) {
+        // The approval page shows the key's limits beside the machine's hostname. `PERMISSIONS` is ox's `Json`, which encodes
+        // bigints. Flags replace the fields they set, and Tempo ID fills what is left with the headless ceiling.
+        const base = Permissions.from(Json.parse(process.env.PERMISSIONS ?? '{}'));
+        // `fund` and `send` use the client's chain, so a key for another chain could not send.
+        if (base.chainId !== undefined && base.chainId !== client.chain.id)
+            return c.error({
+                code: 'CHAIN_MISMATCH',
+                message: `PERMISSIONS names chain ${base.chainId}, but the CLI sends on chain ${client.chain.id}. Remove chainId, or set it to ${client.chain.id}.`,
+            });
+        const device = await client.auth.device.authorize({
+            permissions: Permissions.from({
+                ...base,
+                ...(c.options.expiry ? { expiry: expiry(c.options.expiry) } : {}),
+                ...(c.options.limit
+                    ? {
+                        limits: c.options.limit.flatMap(list).map((value) => {
+                            const [amount, rest] = value.split(':');
+                            const [symbol, period] = rest.split('/');
+                            const listing = token(symbol);
+                            return {
+                                limit: Value.from(amount, listing.decimals),
+                                ...(period ? { period: seconds(period) } : {}),
+                                token: listing.address,
+                            };
+                        }),
+                    }
+                    : {}),
+                ...(c.options.scope
+                    ? {
+                        scopes: c.options.scope.flatMap(list).map((value) => {
+                            const [method, symbol] = value.split(':');
+                            const calls = Scopes.tip20(token(symbol).address);
+                            const scope = calls[method];
+                            if (typeof scope !== 'function')
+                                throw new Error(`Unknown TIP-20 call: ${method}.`);
+                            return scope();
+                        }),
+                    }
+                    : {}),
+            }),
+        });
+        yield `Open ${device.verificationUriComplete}`;
+        yield `and confirm the code ${device.userCode}.`;
+        const authorization = await device.wait().catch((error) => error);
+        if (authorization instanceof Error)
+            return c.error({ code: 'DENIED', message: authorization.message });
+        const { account: _, ...rest } = authorization;
+        const replaced = await Session.read();
+        // The new sign-in is saved first, so a failed write keeps the replaced one usable.
+        const session = await Session.save({
+            ...rest,
+            clientId: app.clientId,
+            url: new URL(app.url).origin,
+        });
+        if (replaced?.refreshToken)
+            await Session.revoke(replaced);
+        // A streaming command prints what it yields, not what it returns.
+        yield `Signed in as ${session.user.email}.`;
+        return c.ok({ email: session.user.email });
+    },
+});
+/** A flag's comma-separated entries. */
+function list(value) {
+    return value.split(',');
+}
+/** A key's expiry from a duration such as `7d`, or a Unix time. */
+function expiry(value) {
+    return /\d$/.test(value) ? Number(value) : Expiry.seconds(seconds(value));
+}
+/** A duration such as `30m`, `12h`, `7d`, or `2w` in seconds. A bare number is seconds. */
+function seconds(value) {
+    const amount = Number.parseInt(value);
+    if (value.endsWith('m'))
+        return amount * 60;
+    if (value.endsWith('h'))
+        return amount * 3_600;
+    if (value.endsWith('d'))
+        return amount * 86_400;
+    if (value.endsWith('w'))
+        return amount * 604_800;
+    return amount;
+}
+/** A Tempo token on the client's chain, by symbol or address. */
+function token(value) {
+    if (/^0x[0-9a-fA-F]{40}$/.test(value))
+        return { address: value, decimals: 6 };
+    const listing = Tokens.tokens.tempo.find((token) => token.symbol?.toLowerCase() === value.toLowerCase());
+    if (!listing)
+        throw new Error(`Unknown Tempo token: ${value}.`);
+    const addresses = listing.addresses;
+    // A local node predeploys the testnet's tokens, and OUSD has its mainnet address everywhere.
+    const address = addresses[client.chain.id] ??
+        (client.chain.id === tempoLocalnet.id
+            ? addresses[tempoTestnet.id]
+            : undefined) ??
+        (listing.symbol === 'OUSD' ? ousd : undefined);
+    if (!address)
+        throw new Error(`${listing.symbol} is not on chain ${client.chain.id}.`);
+    return { address, decimals: listing.decimals };
+}

package/dist/commands/logout.js

@@ -0,0 +1,10 @@
+/** Revokes and forgets the saved tokens. @module */
+import { Cli } from 'incur';
+import * as Session from '../Session.js';
+export default Cli.command({
+    description: 'Sign out on this machine',
+    async run() {
+        const revoked = await Session.remove();
+        return { revoked, signedOut: true };
+    },
+});

package/dist/commands/send.js

@@ -0,0 +1,33 @@
+/** Sends OUSD from the user's Tempo Account with the CLI's access key. @module */
+import { Cli, z } from 'incur';
+import { Value } from 'ox';
+import * as Session from '../Session.js';
+import { client, ousd } from '../viem.config.js';
+export default Cli.command({
+    args: z.object({
+        to: z
+            .string()
+            .regex(/^0x[0-9a-fA-F]{40}$/)
+            .describe('Recipient address'),
+        amount: z
+            .string()
+            .regex(/^\d+(\.\d{1,6})?$/)
+            .describe('Amount of OUSD, such as 0.01'),
+    }),
+    description: 'Send OUSD from your Tempo Account',
+    async run(c) {
+        const session = await Session.get();
+        if (!session)
+            return c.error({
+                code: 'SIGNED_OUT',
+                message: 'Not signed in. Run `login`.',
+            });
+        // `Session.get` set the client's account to the session's key.
+        const { receipt } = await client.token.transferSync({
+            amount: Value.from(c.args.amount, 6),
+            to: c.args.to,
+            token: ousd,
+        });
+        return { status: receipt.status, transactionHash: receipt.transactionHash };
+    },
+});

package/dist/commands/whoami.js

@@ -0,0 +1,20 @@
+/** Prints the signed-in user's email and Tempo Account, refreshing the saved tokens when needed. @module */
+import { Cli } from 'incur';
+import * as Session from '../Session.js';
+import { client } from '../viem.config.js';
+export default Cli.command({
+    description: 'Show who is signed in',
+    async run(c) {
+        const session = await Session.get();
+        if (!session)
+            return c.error({
+                code: 'SIGNED_OUT',
+                message: 'Not signed in. Run `login`.',
+            });
+        // Tempo ID's UserInfo endpoint accepts the access token, as any Tempo API would.
+        const { email } = await client.auth.oauth.userInfo({
+            accessToken: session.accessToken,
+        });
+        return { account: session.key.account, email };
+    },
+});

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * A CLI that signs in through Tempo ID's device grant, with an access key for the user's Tempo
+ * Account. Each command is a file in `commands/`, which incur loads by name.
+ *
+ * ```sh
+ * node index.ts login
+ * node index.ts login --limit 100:OUSD --limit 50:EURC.e --scope transfer:OUSD --expiry 7d
+ * node index.ts whoami
+ * node index.ts fund
+ * node index.ts send 0x000000000000000000000000000000000000dEaD 0.01
+ * node index.ts logout
+ * ```
+ * @module
+ */
+import { Cli } from 'incur';
+await Cli.create('tempo', {
+    description: "Signs in to Tempo through Tempo ID's device grant.",
+})
+    .fs(new URL('./commands/', import.meta.url))
+    .serve();

package/dist/viem.config.js

@@ -0,0 +1,32 @@
+/**
+ * The Viem client the CLI shares, extended with Tempo ID and paying fees in OUSD: Tempo testnet,
+ * or a local Tempo node at `TEMPO_RPC_URL`, as the end-to-end tests run. `TEMPO_ID_URL` points it
+ * at a Tempo ID deployment, such as a pull request's preview, and `CLIENT_ID` names the device app
+ * that it signs in to. A sign-in or a saved session sets its account, so commands send without
+ * naming one.
+ * @module
+ */
+import { Auth, tempoId } from '@tempoxyz/id/client';
+import { http } from 'viem';
+import { createClient } from 'viem/tempo';
+import { tempo, tempoLocalnet, tempoTestnet } from 'viem/tempo/chains';
+import * as Tokens from 'viem/tokens';
+/** OUSD, which the CLI pays fees in and sends. It has its mainnet address on every Tempo chain. */
+export const ousd = Tokens.ousd(tempo.id).address;
+/**
+ * The Tempo ID deployment and the device app that the CLI signs in to. `scripts/seed.ts` registers
+ * the app. `tempo-cli-cash` signs in to Tempo Cash's realm.
+ */
+export const app = {
+    clientId: process.env.CLIENT_ID ?? 'tempo-cli',
+    url: process.env.TEMPO_ID_URL ?? 'http://localhost:5173',
+};
+const rpcUrl = process.env.TEMPO_RPC_URL;
+/** The CLI's Viem client, with Tempo ID's actions and the signed-in account. */
+export const client = createClient({
+    account: Auth.account(),
+    chain: rpcUrl ? tempoLocalnet : tempoTestnet,
+    feeToken: ousd,
+    // Without a URL, the transport uses the chain's own RPC.
+    transport: http(rpcUrl),
+}).extend(tempoId(app));

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@tempoxyz/example-id-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Signs in to Tempo through Tempo ID's device grant.",
+  "type": "module",
+  "bin": {
+    "tempo": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tempoxyz/id.git",
+    "directory": "playgrounds/cli"
+  },
+  "dependencies": {
+    "incur": "0.7.0",
+    "ox": "0.14.56",
+    "viem": "2.57.5",
+    "@tempoxyz/id": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.4",
+    "tsx": "4.23.15",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check:types": "tsc",
+    "start": "node --import tsx --env-file-if-exists=.env index.ts"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.