@calque/grant 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# @calque/grant
 
-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.
+`calque serve` verifies Ed25519-signed dataset grants and mints none: your
+application's backend signs them. `@calque/grant` is that backend's half, with
+no dependency beyond `node:crypto`. It creates the signing key, mints grants
+and tenant orders, and refuses every claim Calque's verifier would answer with
+`401`. [`spec/dataset-grant-v1.md`](https://github.com/calque-sh/calque/blob/main/spec/dataset-grant-v1.md) is the
+format it implements.
+
+```sh
+npm install @calque/grant
+```
+
+It is for a server. The signing key never reaches a browser, so nothing here
+runs in one.
+
+## Create the key
+
+```sh
+npx calque-grant keygen --key-file grant-key.pem --key-id app-1
+```
+
+It writes the private key to `grant-key.pem` as PKCS#8 PEM, readable by its
+owner only, and prints the value `calque serve --grant-verification-key-env`
+reads:
+
+```json
+{ "keyId": "app-1", "publicKey": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo" }
+```
+
+Put that value in the environment variable the flag names, and the same
+`publicKey` in the client's `grantVerificationKey`. Keep the key file in your
+secret store. `keygen` never overwrites a file: a server configured with the
+old key would refuse every grant signed with a new one.
+
+In code, `generateSigningKey()` returns the same key as a `KeyObject`, as
+PKCS#8 DER and PEM, and as the raw public key.
+
+## Mint a grant
+
+```ts
+import { readFileSync } from "node:fs";
+import { loadSigningKey, mintGrant } from "@calque/grant";
+
+const key = loadSigningKey(readFileSync("grant-key.pem"));
+
+const now = Math.floor(Date.now() / 1000);
+const token = mintGrant(
+  {
+    keyId: "app-1",
+    audience: "app.example.com",
+    subject: user.id,
+    attributes: { tenant_id: { int8: "42" } },
+    authorizationGeneration: 1,
+    issuedAtUnixSeconds: now,
+    expiresAtUnixSeconds: now + 900,
+    commands: [{ collection: "tasks", operations: ["update"] }],
+  },
+  key,
+);
+```
+
+Return `token` from the page's `auth()` as `bearerToken`. A grant lasts at most
+900 seconds, so mint one per request, not per session.
+
+`loadSigningKey` takes PEM text, PEM bytes or DER bytes, from PKCS#8 version 1
+or 2. A key from `calque-dev-grant` is a version 2 document, and it loads on
+every supported Node, because the package reads the seed from that layout
+instead of leaving it to the OpenSSL Node bundles.
+
+`mintGrant` throws `GrantRefused` instead of signing a grant `calque serve`
+would answer with `401`:
+
+- a validity window that is empty or longer than 900 seconds;
+- an unknown claim, an empty audience, or one over 256 bytes;
+- a key id that is empty, longer than 128 bytes, or holds a `.` or a character
+  outside printable ASCII;
+- a subject or attribute name that is empty, longer than 512 bytes, or holds a
+  control character;
+- more than 64 attributes, or a value outside its type;
+- more than 64 command capabilities, a collection named twice, an empty or
+  repeated operation, or an operation other than `insert`, `update` and
+  `delete`;
+- a payload over 4096 bytes.
+
+It cannot check `authorizationGeneration` or the audience against a
+deployment: those are the deployment's facts, so a grant for the wrong ones is
+signed and then refused by `calque serve`.
+
+`int8`, `bytes` and `uuid` attributes travel as strings, because a JavaScript
+number cannot hold every 64-bit integer, and a tenant key that lost its low
+bits would authorize the wrong rows. `int8` is a decimal integer, `bytes` is
+hex, and `uuid` is exactly 32 hex digits with no hyphens.
+
+## Tenants
+
+When a scope is partitioned by a grant attribute, each grant names one tenant
+in that attribute, typed as the partition column is: an `int8` column takes
+`{ int8: "42" }`, a `uuid` column takes 32 hex digits. A grant whose attribute
+is missing or of another type is refused.
+
+The backend can also warm, pin, unpin, inspect or evict a tenant.
+`mintTenantOrder` signs such an order with the same key, under a signing domain
+of its own so a browser's grant can never stand in for it, valid for at most
+300 seconds:
+
+```ts
+import { mintTenantOrder } from "@calque/grant";
+
+const order = mintTenantOrder(
+  {
+    keyId: "app-1",
+    audience: "app.example.com",
+    action: "warm",
+    tenant: { int8: "42" },
+    issuedAtUnixSeconds: now,
+    expiresAtUnixSeconds: now + 60,
+  },
+  key,
+);
+await fetch(`${calque}/v1/tenants`, {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ order }),
+});
+```
+
+The answer is the tenant's state, `cold`, `preparing` or `warm`, with whether it
+is pinned and, once it has an artifact, the age of its cut and its size.
+
+Each order carries an `orderId`, 16 random bytes in base64url unless you pass
+one of 16 to 64 base64url characters. Calque acts on an order once: the same
+order posted again, before it expires or after a restart, is answered `409`
+`REPLAYED`, so mint a new order for each request.
+
+## calque-grant mint
+
+```sh
+npx calque-grant mint --key-file grant-key.pem --key-id app-1 \
+  --audience app.example.com --subject me --generation 1 \
+  --lifetime-seconds 900 --command tasks=update
+```
+
+It prints one JSON document: the token, when it expires, the generation, the
+commands and the verification-key value. It is for development and for
+scripts; a backend mints in code.
+
+| Flag                        | What it takes                                                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------------- |
+| `--key-file <path>`         | The signing key, PEM or DER, PKCS#8.                                                          |
+| `--key-id <id>`             | The id the grant and the verification key carry.                                              |
+| `--audience <audience>`     | The audience `calque serve` was started with.                                                 |
+| `--subject <subject>`       | Who the grant is issued to.                                                                   |
+| `--generation <n>`          | The authorization generation the grant is valid for.                                          |
+| `--lifetime-seconds <n>`    | How long it is valid, at most 900.                                                            |
+| `--attribute <n>=<t>:<v>`   | A grant attribute; the type is `uuid`, `bytes`, `int8`, `int4`, `int2` or `bool`. Repeatable. |
+| `--command <c>=<op>[+<op>]` | A write capability for a collection; without one the grant is read-only. Repeatable.          |
+
+`calque-grant` exits 0 on success, 1 when a grant is refused or a file cannot
+be read or written, and 2 on a usage error.
+
+## Node versions
+
+The package supports the Node releases with Node's October 2026 security
+fixes: 26.12.1 or newer, 24.22.1 or newer on the 24 line, or 22.23.4 or newer
+on the 22 line. It runs on Node 20 and newer, the first with
+`String.prototype.isWellFormed`, which checks that text is well-formed
+Unicode. It does not depend on the OpenSSL a Node bundles, and its tests pass
+on Node 20, whose OpenSSL 3.0 cannot read a PKCS#8 version 2 key itself.

package/bin/calque-grant.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { run } from "../dist/cli.js";
+
+process.exitCode = run(process.argv.slice(2), {
+  stdout: process.stdout,
+  stderr: process.stderr,
+  nowUnixSeconds: () => Math.floor(Date.now() / 1000),
+});

package/dist/claims.d.ts

@@ -0,0 +1,73 @@
+import { Buffer } from "node:buffer";
+/** The only payload version Calque accepts. */
+export declare const GRANT_VERSION = 1;
+/**
+ * Prefixed to the payload bytes before signing, NUL byte included. A
+ * signature over the bare payload is refused.
+ */
+export declare const GRANT_SIGNING_DOMAIN = "calque.dataset-grant.v1\0";
+/** The longest validity window Calque accepts: 15 minutes. */
+export declare const MAX_GRANT_LIFETIME_SECONDS: number;
+declare const OPERATIONS: readonly ["insert", "update", "delete"];
+/**
+ * One principal attribute in its wire form. `int8`, `bytes` and `uuid` travel
+ * as strings, because a JavaScript number cannot hold every 64-bit integer,
+ * and a tenant key that lost its low bits would authorize the wrong rows.
+ * `int8` is a decimal integer, `bytes` is hex, and `uuid` is exactly 32 hex
+ * digits with no hyphens.
+ */
+export type GrantAttributeValue = {
+    readonly bool: boolean;
+} | {
+    readonly int2: number;
+} | {
+    readonly int4: number;
+} | {
+    readonly int8: string;
+} | {
+    readonly bytes: string;
+} | {
+    readonly uuid: string;
+};
+export type GrantCommandOperation = (typeof OPERATIONS)[number];
+/** One collection's write capability: exact names, no wildcard. */
+export interface GrantCommandCapability {
+    readonly collection: string;
+    readonly operations: readonly GrantCommandOperation[];
+}
+/** Everything a grant states except its version, which is always 1. */
+export interface DatasetGrantClaims {
+    readonly keyId: string;
+    readonly audience: string;
+    readonly subject: string;
+    readonly attributes: Readonly<Record<string, GrantAttributeValue>>;
+    readonly authorizationGeneration: number;
+    readonly issuedAtUnixSeconds: number;
+    readonly expiresAtUnixSeconds: number;
+    /** Absent or empty is a read-only grant, which authorizes no write. */
+    readonly commands?: readonly GrantCommandCapability[];
+}
+/** A claim Calque's verifier would refuse, refused before it is signed. */
+export declare class GrantRefused extends Error {
+    constructor(message: string);
+}
+export declare function refuse(message: string): never;
+export declare const utf8Bytes: (text: string) => number;
+export declare function wellFormed(field: string, value: unknown): string;
+export declare function keyId(value: unknown): string;
+export declare function audience(value: unknown): string;
+export declare function unsigned(field: string, value: unknown): number;
+/** The attribute value's JSON, exactly as the Rust issuer writes it. */
+export declare function attributeValue(attribute: string, value: unknown): string;
+/**
+ * The signed payload, refused if Calque would refuse it.
+ *
+ * The verifier parses any JSON object with these fields, in any order and with
+ * any whitespace, because the signature covers whatever bytes were sent. These
+ * are the bytes the Rust issuer writes, so the frozen token vectors can check
+ * this package: fields in the order below, no whitespace, attributes sorted by
+ * their UTF-8 bytes, operations in the order given, and `commands` omitted
+ * when empty.
+ */
+export declare function serializeClaims(claims: DatasetGrantClaims): Buffer;
+export {};

package/dist/claims.js

@@ -0,0 +1,225 @@
+import { Buffer } from "node:buffer";
+/** The only payload version Calque accepts. */
+export const GRANT_VERSION = 1;
+/**
+ * Prefixed to the payload bytes before signing, NUL byte included. A
+ * signature over the bare payload is refused.
+ */
+export const GRANT_SIGNING_DOMAIN = "calque.dataset-grant.v1\0";
+/** The longest validity window Calque accepts: 15 minutes. */
+export const MAX_GRANT_LIFETIME_SECONDS = 15 * 60;
+const MAX_PAYLOAD_BYTES = 4 * 1024;
+const MAX_KEY_ID_BYTES = 128;
+const MAX_AUDIENCE_BYTES = 256;
+const MAX_NAME_BYTES = 512;
+const MAX_ATTRIBUTES = 64;
+const MAX_COMMAND_CAPABILITIES = 64;
+const MAX_COLLECTION_BYTES = 128;
+const OPERATIONS = ["insert", "update", "delete"];
+const CLAIMS = new Set([
+    "keyId",
+    "audience",
+    "subject",
+    "attributes",
+    "authorizationGeneration",
+    "issuedAtUnixSeconds",
+    "expiresAtUnixSeconds",
+    "commands",
+]);
+/** A claim Calque's verifier would refuse, refused before it is signed. */
+export class GrantRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GrantRefused";
+    }
+}
+export function refuse(message) {
+    throw new GrantRefused(message);
+}
+export const utf8Bytes = (text) => Buffer.byteLength(text, "utf8");
+/** Rust's `u8::is_ascii_graphic`: `!` through `~`. */
+const ASCII_GRAPHIC = /^[\x21-\x7e]+$/;
+/** The same, without `.`, which separates a token's two halves. */
+const KEY_ID = /^[\x21-\x2d\x2f-\x7e]+$/;
+/** Rust's `char::is_control`, general category Cc. */
+const CONTROL = /\p{Cc}/u;
+export function wellFormed(field, value) {
+    if (typeof value !== "string" || !value.isWellFormed())
+        refuse(`${field} must be a string of well-formed Unicode`);
+    return value;
+}
+export function keyId(value) {
+    const text = wellFormed("keyId", value);
+    if (utf8Bytes(text) > MAX_KEY_ID_BYTES || !KEY_ID.test(text))
+        refuse(`keyId must be 1 to ${String(MAX_KEY_ID_BYTES)} printable ASCII characters other than "."`);
+    return text;
+}
+export function audience(value) {
+    const text = wellFormed("audience", value);
+    if (text === "" || utf8Bytes(text) > MAX_AUDIENCE_BYTES)
+        refuse(`audience must be 1 to ${String(MAX_AUDIENCE_BYTES)} bytes`);
+    return text;
+}
+/** A subject or an attribute name, as `authz::Principal::new` checks it. */
+function name(field, value) {
+    const text = wellFormed(field, value);
+    if (text === "" || utf8Bytes(text) > MAX_NAME_BYTES || CONTROL.test(text))
+        refuse(`${field} must be 1 to ${String(MAX_NAME_BYTES)} bytes of UTF-8 with no control character`);
+    return text;
+}
+export function unsigned(field, value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        refuse(`${field} must be a whole number from 0 to ${String(Number.MAX_SAFE_INTEGER)}`);
+    return value;
+}
+function integer(field, value, minimum, maximum) {
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < minimum ||
+        value > maximum)
+        refuse(`${field} must be a whole number from ${String(minimum)} to ${String(maximum)}`);
+    return value;
+}
+/** The attribute value's JSON, exactly as the Rust issuer writes it. */
+export function attributeValue(attribute, value) {
+    const field = `attribute ${attribute}`;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        refuse(`${field} must be an object naming one type`);
+    const entries = Object.entries(value);
+    const [entry] = entries;
+    if (entry === undefined || entries.length !== 1)
+        refuse(`${field} must name exactly one type`);
+    const [type, raw] = entry;
+    switch (type) {
+        case "bool":
+            if (typeof raw !== "boolean")
+                refuse(`${field} must be true or false`);
+            return `{"bool":${String(raw)}}`;
+        case "int2":
+            return `{"int2":${String(integer(field, raw, -32_768, 32_767))}}`;
+        case "int4":
+            return `{"int4":${String(integer(field, raw, -2_147_483_648, 2_147_483_647))}}`;
+        case "int8":
+            if (typeof raw !== "string" ||
+                !/^[+-]?[0-9]+$/.test(raw) ||
+                BigInt(raw) < -(2n ** 63n) ||
+                BigInt(raw) >= 2n ** 63n)
+                refuse(`${field} must be a decimal string within a signed 64-bit integer`);
+            return `{"int8":${JSON.stringify(raw)}}`;
+        case "bytes":
+            if (typeof raw !== "string" || !/^(?:[0-9a-fA-F]{2})*$/.test(raw))
+                refuse(`${field} must be hex with an even number of digits`);
+            return `{"bytes":${JSON.stringify(raw)}}`;
+        case "uuid":
+            if (typeof raw !== "string" || !/^[0-9a-fA-F]{32}$/.test(raw))
+                refuse(`${field} must be 32 hex digits with no hyphens`);
+            return `{"uuid":${JSON.stringify(raw)}}`;
+        default:
+            return refuse(`${field} has unknown type ${type}; the types are bool, int2, int4, int8, bytes and uuid`);
+    }
+}
+/**
+ * Sorted by their UTF-8 bytes, which is how a Rust `BTreeMap` orders them.
+ * `Array.prototype.sort` compares UTF-16 code units and disagrees above
+ * U+FFFF, and an object's own key order puts integer-like keys first.
+ */
+function attributes(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        refuse("attributes must be an object, empty for none");
+    const entries = Object.entries(value);
+    if (entries.length > MAX_ATTRIBUTES)
+        refuse(`a grant carries at most ${String(MAX_ATTRIBUTES)} attributes, not ${String(entries.length)}`);
+    return entries
+        .map(([attribute, raw]) => ({
+        key: Buffer.from(name("attribute name", attribute), "utf8"),
+        json: `${JSON.stringify(attribute)}:${attributeValue(attribute, raw)}`,
+    }))
+        .sort((left, right) => Buffer.compare(left.key, right.key))
+        .map(({ json }) => json)
+        .join(",");
+}
+/**
+ * The write capability's JSON, or undefined when there is none, since the Rust
+ * issuer omits an empty `commands`.
+ */
+function commands(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        refuse("commands must be a list");
+    if (value.length === 0)
+        return undefined;
+    if (value.length > MAX_COMMAND_CAPABILITIES)
+        refuse(`a grant carries at most ${String(MAX_COMMAND_CAPABILITIES)} command capabilities`);
+    const named = new Set();
+    const entries = value.map((capability) => {
+        if (typeof capability !== "object" || capability === null)
+            refuse("a command capability must be an object");
+        const fields = Object.keys(capability);
+        if (fields.length !== 2 ||
+            !fields.includes("collection") ||
+            !fields.includes("operations"))
+            refuse(`a command capability has exactly a collection and its operations, not ${fields.join(", ")}`);
+        const { collection, operations } = capability;
+        if (typeof collection !== "string" ||
+            collection.length > MAX_COLLECTION_BYTES ||
+            !ASCII_GRAPHIC.test(collection))
+            refuse(`a collection is 1 to ${String(MAX_COLLECTION_BYTES)} printable ASCII characters`);
+        if (named.has(collection))
+            refuse(`collection ${collection} is named twice`);
+        named.add(collection);
+        if (!Array.isArray(operations) || operations.length === 0)
+            refuse(`collection ${collection} names no operation; an empty set is refused, never read as every operation`);
+        const seen = new Set();
+        for (const operation of operations) {
+            if (!OPERATIONS.includes(operation))
+                refuse(`collection ${collection} names ${JSON.stringify(operation)}; the operations are insert, update and delete`);
+            if (seen.has(operation))
+                refuse(`collection ${collection} repeats ${String(operation)}`);
+            seen.add(operation);
+        }
+        return `{"collection":${JSON.stringify(collection)},"operations":${JSON.stringify(operations)}}`;
+    });
+    return `[${entries.join(",")}]`;
+}
+/**
+ * The signed payload, refused if Calque would refuse it.
+ *
+ * The verifier parses any JSON object with these fields, in any order and with
+ * any whitespace, because the signature covers whatever bytes were sent. These
+ * are the bytes the Rust issuer writes, so the frozen token vectors can check
+ * this package: fields in the order below, no whitespace, attributes sorted by
+ * their UTF-8 bytes, operations in the order given, and `commands` omitted
+ * when empty.
+ */
+export function serializeClaims(claims) {
+    for (const field of Object.keys(claims))
+        if (!CLAIMS.has(field))
+            refuse(`${field} is not a grant claim; Calque refuses a payload with an unknown field`);
+    const issued = unsigned("issuedAtUnixSeconds", claims.issuedAtUnixSeconds);
+    const expires = unsigned("expiresAtUnixSeconds", claims.expiresAtUnixSeconds);
+    if (expires <= issued)
+        refuse("expiresAtUnixSeconds must be later than issuedAtUnixSeconds");
+    if (expires - issued > MAX_GRANT_LIFETIME_SECONDS)
+        refuse(`the validity window is ${String(expires - issued)} s; Calque refuses one longer than ${String(MAX_GRANT_LIFETIME_SECONDS)} s`);
+    const fields = [
+        `"version":${String(GRANT_VERSION)}`,
+        `"keyId":${JSON.stringify(keyId(claims.keyId))}`,
+        `"audience":${JSON.stringify(audience(claims.audience))}`,
+        `"subject":${JSON.stringify(name("subject", claims.subject))}`,
+        `"attributes":{${attributes(claims.attributes)}}`,
+        `"authorizationGeneration":${String(unsigned("authorizationGeneration", claims.authorizationGeneration))}`,
+        `"issuedAtUnixSeconds":${String(issued)}`,
+        `"expiresAtUnixSeconds":${String(expires)}`,
+    ];
+    const capabilities = commands(claims.commands);
+    if (capabilities !== undefined)
+        fields.push(`"commands":${capabilities}`);
+    const payload = Buffer.from(`{${fields.join(",")}}`, "utf8");
+    // Within this bound a token is at most 5,549 bytes, inside the verifier's
+    // 8 KiB token bound, so that one needs no check of its own.
+    if (payload.length > MAX_PAYLOAD_BYTES)
+        refuse(`the payload is ${String(payload.length)} bytes; Calque refuses one over ${String(MAX_PAYLOAD_BYTES)}`);
+    return payload;
+}
+//# sourceMappingURL=claims.js.map

package/dist/claims.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+interface Output {
+    write(text: string): unknown;
+}
+/** What `run` needs from the process, so a test can stand in for it. */
+export interface Environment {
+    readonly stdout: Output;
+    readonly stderr: Output;
+    readonly nowUnixSeconds: () => number;
+}
+/** Runs `calque-grant` over `argv` and returns its exit status. */
+export declare function run(argv: readonly string[], io: Environment): number;
+export {};

package/dist/cli.js

@@ -0,0 +1,229 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+import {} from "./claims.js";
+import { generateSigningKey, loadSigningKey, verificationKeyEnvironment, } from "./key.js";
+import { mintGrant } from "./mint.js";
+const USAGE = `usage: calque-grant keygen --key-file <path> --key-id <id>
+       calque-grant mint --key-file <path> --key-id <id> --audience <audience>
+                         --subject <subject> --generation <n> --lifetime-seconds <n>
+                         [--attribute <name>=<type>:<value>]...
+                         [--command <collection>=<operation>[+<operation>]]...
+`;
+const HELP = `${USAGE}
+keygen  Creates an Ed25519 signing key at --key-file, as PKCS#8 PEM readable
+        by owner only, and prints the {"keyId":...,"publicKey":...} value that
+        \`calque serve --grant-verification-key-env\` reads. It never overwrites
+        a file.
+
+mint    Signs one dataset grant with the key at --key-file and prints it as one
+        JSON document, with when it expires and the verification-key value.
+        --lifetime-seconds is at most 900. An attribute type is uuid (32 hex
+        digits), bytes (hex), int8, int4, int2 or bool. A command names a
+        collection and insert, update or delete; without one the grant is
+        read-only.
+
+      --key-file <path>          the signing key, PEM or DER, PKCS#8
+      --key-id <id>              the id the grant and the verification key carry
+      --audience <audience>      the audience \`calque serve\` was started with
+      --subject <subject>        who the grant is issued to
+      --generation <n>           the authorization generation it is valid for
+      --lifetime-seconds <n>     how long it is valid
+      --attribute <n>=<t>:<v>    repeat for more than one
+      --command <c>=<op>[+<op>]  repeat per collection
+  -h, --help                     print this text
+
+Exit status: 0 on success, 1 when a grant is refused or a file cannot be read
+or written, 2 on a usage error.
+`;
+class UsageError extends Error {
+}
+const WHOLE_NUMBER = /^[0-9]+$/u;
+const SIGNED_NUMBER = /^[+-]?[0-9]+$/u;
+/** `<name>=<type>:<value>`, in the vocabulary `calque-dev-grant` reads. */
+function parseAttribute(argument) {
+    const equals = argument.indexOf("=");
+    const colon = argument.indexOf(":", equals + 1);
+    if (equals === -1 || colon === -1)
+        throw new UsageError(`--attribute ${argument} is not <name>=<type>:<value>`);
+    const name = argument.slice(0, equals);
+    const type = argument.slice(equals + 1, colon);
+    const value = argument.slice(colon + 1);
+    switch (type) {
+        case "uuid":
+            return [name, { uuid: value }];
+        case "bytes":
+            return [name, { bytes: value }];
+        case "int8":
+            return [name, { int8: value }];
+        case "int4":
+        case "int2":
+            if (!SIGNED_NUMBER.test(value))
+                throw new UsageError(`--attribute ${name} is not an ${type}`);
+            return [
+                name,
+                type === "int4" ? { int4: Number(value) } : { int2: Number(value) },
+            ];
+        case "bool":
+            if (value !== "true" && value !== "false")
+                throw new UsageError(`--attribute ${name} is not a bool`);
+            return [name, { bool: value === "true" }];
+        default:
+            throw new UsageError(`--attribute ${name} has unknown type ${type}`);
+    }
+}
+/** `<collection>=<operation>[+<operation>…]`; there is no wildcard. */
+function parseCommand(argument) {
+    const equals = argument.indexOf("=");
+    if (equals === -1)
+        throw new UsageError(`--command ${argument} is not <collection>=<operation>[+…]`);
+    return {
+        collection: argument.slice(0, equals),
+        // `mintGrant` refuses an operation outside the three.
+        operations: argument
+            .slice(equals + 1)
+            .split("+"),
+    };
+}
+const OPTIONS = {
+    "key-file": { type: "string", multiple: true },
+    "key-id": { type: "string", multiple: true },
+    audience: { type: "string", multiple: true },
+    subject: { type: "string", multiple: true },
+    generation: { type: "string", multiple: true },
+    "lifetime-seconds": { type: "string", multiple: true },
+    attribute: { type: "string", multiple: true },
+    command: { type: "string", multiple: true },
+    help: { type: "boolean", short: "h" },
+};
+function parseFlags(argv) {
+    try {
+        return parseArgs({
+            args: [...argv],
+            options: OPTIONS,
+            strict: true,
+            allowPositionals: false,
+        }).values;
+    }
+    catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : String(error));
+    }
+}
+function single(flags, name) {
+    const given = flags[name];
+    if (given === undefined)
+        throw new UsageError(`--${name} is required`);
+    if (given.length > 1)
+        throw new UsageError(`--${name} was given twice`);
+    const [value] = given;
+    if (value === undefined)
+        throw new UsageError(`--${name} is required`);
+    return value;
+}
+function wholeNumber(flags, name) {
+    const value = single(flags, name);
+    if (!WHOLE_NUMBER.test(value))
+        throw new UsageError(`--${name} must be a whole number`);
+    return Number(value);
+}
+function rejectOtherFlags(flags, allowed) {
+    for (const name of Object.keys(flags))
+        if (name !== "help" && !allowed.includes(name))
+            throw new UsageError(`unknown argument --${name}`);
+}
+function keygen(flags, io) {
+    rejectOtherFlags(flags, ["key-file", "key-id"]);
+    const path = single(flags, "key-file");
+    const id = single(flags, "key-id");
+    const { privateKey, pem } = generateSigningKey();
+    // Checked before anything is written, so a bad id leaves no key behind.
+    const environment = verificationKeyEnvironment(id, privateKey);
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        writeFileSync(path, pem, { flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error(`${path} exists, and keygen never overwrites a key: a server configured with the old one would refuse every grant signed with a new one`);
+        throw error;
+    }
+    io.stdout.write(`${environment}\n`);
+}
+const MINT_FLAGS = [
+    "key-file",
+    "key-id",
+    "audience",
+    "subject",
+    "generation",
+    "lifetime-seconds",
+    "attribute",
+    "command",
+];
+function mint(flags, io) {
+    rejectOtherFlags(flags, MINT_FLAGS);
+    const attributes = {};
+    for (const argument of flags.attribute ?? []) {
+        const [name, attribute] = parseAttribute(argument);
+        if (Object.hasOwn(attributes, name))
+            throw new UsageError(`--attribute ${name} was given twice`);
+        attributes[name] = attribute;
+    }
+    const commands = (flags.command ?? []).map(parseCommand);
+    const keyId = single(flags, "key-id");
+    const subject = single(flags, "subject");
+    const generation = wholeNumber(flags, "generation");
+    const lifetime = wholeNumber(flags, "lifetime-seconds");
+    const audience = single(flags, "audience");
+    const keyFile = single(flags, "key-file");
+    const key = loadSigningKey(readFileSync(keyFile));
+    const issued = io.nowUnixSeconds();
+    const token = mintGrant({
+        keyId,
+        audience,
+        subject,
+        attributes,
+        authorizationGeneration: generation,
+        issuedAtUnixSeconds: issued,
+        expiresAtUnixSeconds: issued + lifetime,
+        commands,
+    }, key);
+    // The keys in the order `calque-dev-grant` prints them.
+    io.stdout.write(`${JSON.stringify({
+        authorizationGeneration: generation,
+        commands: commands.map(({ collection, operations }) => `${collection}:${operations.join("+")}`),
+        expiresAtUnixSeconds: issued + lifetime,
+        issuedAtUnixSeconds: issued,
+        subject,
+        token,
+        verificationKeyEnvironment: JSON.parse(verificationKeyEnvironment(keyId, key)),
+    }, null, 2)}\n`);
+}
+/** Runs `calque-grant` over `argv` and returns its exit status. */
+export function run(argv, io) {
+    try {
+        const [command, ...rest] = argv;
+        if (command === undefined || command === "-h" || command === "--help") {
+            (command === undefined ? io.stderr : io.stdout).write(command === undefined ? USAGE : HELP);
+            return command === undefined ? 2 : 0;
+        }
+        if (command !== "keygen" && command !== "mint")
+            throw new UsageError(`unknown command ${command}`);
+        const flags = parseFlags(rest);
+        if (flags.help === true) {
+            io.stdout.write(HELP);
+            return 0;
+        }
+        (command === "keygen" ? keygen : mint)(flags, io);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (error instanceof UsageError) {
+            io.stderr.write(`calque-grant: ${message}\n${USAGE}`);
+            return 2;
+        }
+        io.stderr.write(`calque-grant: ${message}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAIN,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,0BAA0B,GAC3B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAatC,MAAM,KAAK,GAAG;;;;;CAKb,CAAC;AAEF,MAAM,IAAI,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;CAyBpB,CAAC;AAEF,MAAM,UAAW,SAAQ,KAAK;CAAG;AAEjC,MAAM,YAAY,GAAG,WAAW,CAAC;AACjC,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAEvC,2EAA2E;AAC3E,SAAS,cAAc,CAAC,QAAgB;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC;IAChD,IAAI,MAAM,KAAK,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;QAC/B,MAAM,IAAI,UAAU,CAClB,eAAe,QAAQ,+BAA+B,CACvD,CAAC;IACJ,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACxC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACjC,KAAK,OAAO;YACV,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAClC,KAAK,MAAM;YACT,OAAO,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACjC,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC;gBAC5B,MAAM,IAAI,UAAU,CAAC,eAAe,IAAI,cAAc,IAAI,EAAE,CAAC,CAAC;YAChE,OAAO;gBACL,IAAI;gBACJ,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE;aACpE,CAAC;QACJ,KAAK,MAAM;YACT,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,OAAO;gBACvC,MAAM,IAAI,UAAU,CAAC,eAAe,IAAI,gBAAgB,CAAC,CAAC;YAC5D,OAAO,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,KAAK,MAAM,EAAE,CAAC,CAAC;QAC5C;YACE,MAAM,IAAI,UAAU,CAAC,eAAe,IAAI,qBAAqB,IAAI,EAAE,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,SAAS,YAAY,CAAC,QAAgB;IACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,CAAC,CAAC;QACf,MAAM,IAAI,UAAU,CAClB,aAAa,QAAQ,sCAAsC,CAC5D,CAAC;IACJ,OAAO;QACL,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC;QACrC,sDAAsD;QACtD,UAAU,EAAE,QAAQ;aACjB,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;aACjB,KAAK,CAAC,GAAG,CAA4B;KACzC,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,GAAG;IACd,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC9C,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC5C,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC5C,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC3C,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC9C,kBAAkB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IACtD,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC7C,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC3C,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE;CAC7B,CAAC;AAIX,SAAS,UAAU,CAAC,IAAuB;IACzC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC;YACf,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,OAAO;YAChB,MAAM,EAAE,IAAI;YACZ,gBAAgB,EAAE,KAAK;SACxB,CAAC,CAAC,MAAM,CAAC;IACZ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,UAAU,CAClB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CACb,KAAY,EACZ,IAA4D;IAE5D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,UAAU,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC;IACvE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,KAAK,IAAI,kBAAkB,CAAC,CAAC;IACxE,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;IACtB,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,UAAU,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC;IACvE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,KAAY,EAAE,IAAuC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAC3B,MAAM,IAAI,UAAU,CAAC,KAAK,IAAI,yBAAyB,CAAC,CAAC;IAC3D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAY,EAAE,OAA0B;IAChE,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;QACnC,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;YAC5C,MAAM,IAAI,UAAU,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,MAAM,CAAC,KAAY,EAAE,EAAe;IAC3C,gBAAgB,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACvC,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,kBAAkB,EAAE,CAAC;IACjD,wEAAwE;IACxE,MAAM,WAAW,GAAG,0BAA0B,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAC/D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACxD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YACpD,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,iIAAiI,CACzI,CAAC;QACJ,MAAM,KAAK,CAAC;IACd,CAAC;IACD,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,GAAG;IACjB,UAAU;IACV,QAAQ;IACR,UAAU;IACV,SAAS;IACT,YAAY;IACZ,kBAAkB;IAClB,WAAW;IACX,SAAS;CACV,CAAC;AAEF,SAAS,IAAI,CAAC,KAAY,EAAE,EAAe;IACzC,gBAAgB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACpC,MAAM,UAAU,GAAwC,EAAE,CAAC;IAC3D,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC;YACjC,MAAM,IAAI,UAAU,CAAC,eAAe,IAAI,kBAAkB,CAAC,CAAC;QAC9D,UAAU,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IAC/B,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAE1C,MAAM,GAAG,GAAG,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,SAAS,CACrB;QACE,KAAK;QACL,QAAQ;QACR,OAAO;QACP,UAAU;QACV,uBAAuB,EAAE,UAAU;QACnC,mBAAmB,EAAE,MAAM;QAC3B,oBAAoB,EAAE,MAAM,GAAG,QAAQ;QACvC,QAAQ;KACT,EACD,GAAG,CACJ,CAAC;IACF,wDAAwD;IACxD,EAAE,CAAC,MAAM,CAAC,KAAK,CACb,GAAG,IAAI,CAAC,SAAS,CACf;QACE,uBAAuB,EAAE,UAAU;QACnC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CACpB,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,CAC7B,GAAG,UAAU,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAC1C;QACD,oBAAoB,EAAE,MAAM,GAAG,QAAQ;QACvC,mBAAmB,EAAE,MAAM;QAC3B,OAAO;QACP,KAAK;QACL,0BAA0B,EAAE,IAAI,CAAC,KAAK,CACpC,0BAA0B,CAAC,KAAK,EAAE,GAAG,CAAC,CAC5B;KACb,EACD,IAAI,EACJ,CAAC,CACF,IAAI,CACN,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,GAAG,CAAC,IAAuB,EAAE,EAAe;IAC1D,IAAI,CAAC;QACH,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAChC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;YACtE,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,KAAK,CACnD,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CACrC,CAAC;YACF,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM;YAC5C,MAAM,IAAI,UAAU,CAAC,mBAAmB,OAAO,EAAE,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACxB,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACtB,OAAO,CAAC,CAAC;QACX,CAAC;QACD,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;YAChC,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC;YACtD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,OAAO,IAAI,CAAC,CAAC;QAC9C,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { GRANT_SIGNING_DOMAIN, GRANT_VERSION, GrantRefused, MAX_GRANT_LIFETIME_SECONDS, } from "./claims.js";
+export type { DatasetGrantClaims, GrantAttributeValue, GrantCommandCapability, GrantCommandOperation, } from "./claims.js";
+export { generateSigningKey, loadSigningKey, verificationKeyEnvironment, } from "./key.js";
+export type { GeneratedSigningKey } from "./key.js";
+export { MAX_TENANT_ORDER_LIFETIME_SECONDS, mintGrant, mintTenantOrder, TENANT_ORDER_SIGNING_DOMAIN, } from "./mint.js";
+export type { TenantAction, TenantOrderClaims } from "./mint.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { GRANT_SIGNING_DOMAIN, GRANT_VERSION, GrantRefused, MAX_GRANT_LIFETIME_SECONDS, } from "./claims.js";
+export { generateSigningKey, loadSigningKey, verificationKeyEnvironment, } from "./key.js";
+export { MAX_TENANT_ORDER_LIFETIME_SECONDS, mintGrant, mintTenantOrder, TENANT_ORDER_SIGNING_DOMAIN, } from "./mint.js";
+//# 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,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAOrB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,0BAA0B,GAC3B,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,iCAAiC,EACjC,SAAS,EACT,eAAe,EACf,2BAA2B,GAC5B,MAAM,WAAW,CAAC"}

package/dist/key.d.ts

@@ -0,0 +1,30 @@
+import { Buffer } from "node:buffer";
+import { type KeyObject } from "node:crypto";
+/** A fresh Ed25519 signing key, in every form a backend stores it in. */
+export interface GeneratedSigningKey {
+    readonly privateKey: KeyObject;
+    /** The private key as a PKCS#8 version 1 DER document. */
+    readonly pkcs8: Buffer;
+    /** The same document as PEM text, which a secret store holds as a string. */
+    readonly pem: string;
+    /** The raw 32-byte public key in unpadded base64url. */
+    readonly publicKey: string;
+}
+export declare function ed25519(key: KeyObject): KeyObject;
+/**
+ * A new Ed25519 key pair from the platform's random source. The private key is
+ * written as PKCS#8 version 1, which every Node that supports Ed25519 reads.
+ */
+export declare function generateSigningKey(): GeneratedSigningKey;
+/**
+ * The private key from a PKCS#8 Ed25519 document, as PEM text or DER bytes,
+ * version 1 or 2. `calque-grant keygen` writes PEM; `calque-dev-grant` writes
+ * DER, as version 2. A document of another kind of key is refused.
+ */
+export declare function loadSigningKey(document: Uint8Array | string): KeyObject;
+/**
+ * The `{"keyId":…,"publicKey":…}` value a deployment's
+ * `--grant-verification-key-env` variable holds for this key: the raw 32-byte
+ * public key, unpadded base64url.
+ */
+export declare function verificationKeyEnvironment(id: string, key: KeyObject): string;

package/dist/key.js

@@ -0,0 +1,113 @@
+import { Buffer } from "node:buffer";
+import { createPrivateKey, createPublicKey, generateKeyPairSync, } from "node:crypto";
+import { keyId } from "./claims.js";
+export function ed25519(key) {
+    if (key.asymmetricKeyType !== "ed25519")
+        throw new TypeError(`a grant is signed with an Ed25519 key, not ${String(key.asymmetricKeyType)}`);
+    return key;
+}
+function rawPublicKey(key) {
+    const { x } = createPublicKey(key).export({ format: "jwk" });
+    if (x === undefined)
+        throw new TypeError("the key exported no public half");
+    return x;
+}
+/**
+ * A new Ed25519 key pair from the platform's random source. The private key is
+ * written as PKCS#8 version 1, which every Node that supports Ed25519 reads.
+ */
+export function generateSigningKey() {
+    const { privateKey } = generateKeyPairSync("ed25519");
+    return {
+        privateKey,
+        pkcs8: privateKey.export({ format: "der", type: "pkcs8" }),
+        pem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+        publicKey: rawPublicKey(privateKey),
+    };
+}
+const PKCS8_V1_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const PKCS8_V2_PREFIX = Buffer.from("3051020101300506032b657004220420", "hex");
+const PKCS8_V2_PUBLIC_KEY_PREFIX = Buffer.from("812100", "hex");
+const SEED_BYTES = 32;
+const PKCS8_V2_BYTES = PKCS8_V2_PREFIX.length +
+    SEED_BYTES +
+    PKCS8_V2_PUBLIC_KEY_PREFIX.length +
+    SEED_BYTES;
+function fromSeed(seed) {
+    return createPrivateKey({
+        key: Buffer.concat([PKCS8_V1_PREFIX, seed]),
+        format: "der",
+        type: "pkcs8",
+    });
+}
+/**
+ * The seed of an Ed25519 PKCS#8 version 2 document in the layout
+ * `calque-dev-grant` and ring write: the algorithm identifier, the seed, then
+ * the public key as the `[1]` field. Undefined for any other bytes. A public
+ * key that is not the seed's is refused.
+ */
+function versionTwoSeed(der) {
+    if (der.length !== PKCS8_V2_BYTES)
+        return undefined;
+    const seedAt = PKCS8_V2_PREFIX.length;
+    const publicAt = seedAt + SEED_BYTES + PKCS8_V2_PUBLIC_KEY_PREFIX.length;
+    if (!der.subarray(0, seedAt).equals(PKCS8_V2_PREFIX) ||
+        !der
+            .subarray(seedAt + SEED_BYTES, publicAt)
+            .equals(PKCS8_V2_PUBLIC_KEY_PREFIX))
+        return undefined;
+    const seed = der.subarray(seedAt, seedAt + SEED_BYTES);
+    const embedded = der.subarray(publicAt).toString("base64url");
+    if (rawPublicKey(fromSeed(seed)) !== embedded)
+        throw new TypeError("the key document's public key is not the one its private key derives");
+    return seed;
+}
+function fromDer(der) {
+    // A version 2 document in the layout above is read from its seed on every
+    // Node, because OpenSSL before 3.5, which Node bundles up to 22.19 and
+    // 24.4, refuses version 2.
+    const seed = versionTwoSeed(der);
+    return seed === undefined
+        ? createPrivateKey({ key: der, format: "der", type: "pkcs8" })
+        : fromSeed(seed);
+}
+const PEM_LABEL = /^-----BEGIN PRIVATE KEY-----\s*([A-Za-z0-9+/=\s]+?)\s*-----END PRIVATE KEY-----\s*$/u;
+/**
+ * The private key from a PKCS#8 Ed25519 document, as PEM text or DER bytes,
+ * version 1 or 2. `calque-grant keygen` writes PEM; `calque-dev-grant` writes
+ * DER, as version 2. A document of another kind of key is refused.
+ */
+export function loadSigningKey(document) {
+    const bytes = typeof document === "string"
+        ? Buffer.from(document, "utf8")
+        : Buffer.from(document);
+    const text = bytes.toString("latin1").trimStart();
+    let key;
+    try {
+        if (text.startsWith("-----BEGIN")) {
+            const body = PEM_LABEL.exec(text)?.[1];
+            if (body === undefined)
+                throw new TypeError("the PEM document is not a PRIVATE KEY block of PKCS#8");
+            key = fromDer(Buffer.from(body.replace(/\s+/gu, ""), "base64"));
+        }
+        else {
+            key = fromDer(bytes);
+        }
+    }
+    catch (cause) {
+        throw new TypeError(`the document is not a PKCS#8 Ed25519 private key in PEM or DER: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    return ed25519(key);
+}
+/**
+ * The `{"keyId":…,"publicKey":…}` value a deployment's
+ * `--grant-verification-key-env` variable holds for this key: the raw 32-byte
+ * public key, unpadded base64url.
+ */
+export function verificationKeyEnvironment(id, key) {
+    return JSON.stringify({
+        keyId: keyId(id),
+        publicKey: rawPublicKey(ed25519(key)),
+    });
+}
+//# sourceMappingURL=key.js.map

package/dist/key.js.map

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

package/dist/mint.d.ts

@@ -0,0 +1,46 @@
+import { type KeyObject } from "node:crypto";
+import { type DatasetGrantClaims, type GrantAttributeValue } from "./claims.js";
+/**
+ * Prefixed to a tenant order's payload before signing, so that neither a
+ * dataset grant nor a tenant order verifies as the other.
+ */
+export declare const TENANT_ORDER_SIGNING_DOMAIN = "calque.tenant-order.v1\0";
+/** The longest validity window Calque accepts for a tenant order: 5 minutes. */
+export declare const MAX_TENANT_ORDER_LIFETIME_SECONDS: number;
+/**
+ * `warm` prepares the tenant now, `pin` keeps it warm whatever its recency,
+ * `unpin` hands it back to recency, `state` changes nothing, and `evict` drops
+ * its artifact, pin and recency so its next open is cold.
+ */
+export type TenantAction = "warm" | "pin" | "unpin" | "state" | "evict";
+/** Everything a tenant order states except its version, which is always 1. */
+export interface TenantOrderClaims {
+    readonly keyId: string;
+    readonly audience: string;
+    /**
+     * Unique to this order, which Calque acts on once: 16 to 64 base64url
+     * characters. Left out, it is 16 random bytes.
+     */
+    readonly orderId?: string;
+    readonly action: TenantAction;
+    /** The tenant, typed as the grant attribute that names it. */
+    readonly tenant: GrantAttributeValue;
+    readonly issuedAtUnixSeconds: number;
+    readonly expiresAtUnixSeconds: number;
+}
+/**
+ * `base64url(payload).base64url(signature)`, both unpadded, where the
+ * signature is Ed25519 over the domain, then the payload.
+ */
+export declare function signUnder(domain: string, payload: Uint8Array, key: KeyObject): string;
+/**
+ * A signed grant for exactly these claims, or a `GrantRefused` for claims
+ * Calque's verifier would answer with 401.
+ */
+export declare function mintGrant(claims: DatasetGrantClaims, key: KeyObject): string;
+/**
+ * The order the backend posts as `{"order": …}` to `POST /v1/tenants`, signed
+ * with the grant key. Only the backend holds that key, so a browser cannot
+ * warm, pin or inspect a tenant.
+ */
+export declare function mintTenantOrder(claims: TenantOrderClaims, key: KeyObject): string;

package/dist/mint.js

@@ -0,0 +1,64 @@
+import { Buffer } from "node:buffer";
+import { randomBytes, sign } from "node:crypto";
+import { attributeValue, audience, GRANT_SIGNING_DOMAIN, keyId, refuse, serializeClaims, unsigned, } from "./claims.js";
+import { ed25519 } from "./key.js";
+/**
+ * Prefixed to a tenant order's payload before signing, so that neither a
+ * dataset grant nor a tenant order verifies as the other.
+ */
+export const TENANT_ORDER_SIGNING_DOMAIN = "calque.tenant-order.v1\0";
+/** The longest validity window Calque accepts for a tenant order: 5 minutes. */
+export const MAX_TENANT_ORDER_LIFETIME_SECONDS = 5 * 60;
+const TENANT_ACTIONS = new Set([
+    "warm",
+    "pin",
+    "unpin",
+    "state",
+    "evict",
+]);
+/**
+ * `base64url(payload).base64url(signature)`, both unpadded, where the
+ * signature is Ed25519 over the domain, then the payload.
+ */
+export function signUnder(domain, payload, key) {
+    if (key.type !== "private")
+        throw new TypeError("a grant is signed with a private key");
+    const signature = sign(null, Buffer.concat([Buffer.from(domain, "utf8"), payload]), ed25519(key));
+    return `${Buffer.from(payload).toString("base64url")}.${signature.toString("base64url")}`;
+}
+/**
+ * A signed grant for exactly these claims, or a `GrantRefused` for claims
+ * Calque's verifier would answer with 401.
+ */
+export function mintGrant(claims, key) {
+    return signUnder(GRANT_SIGNING_DOMAIN, serializeClaims(claims), key);
+}
+/**
+ * The order the backend posts as `{"order": …}` to `POST /v1/tenants`, signed
+ * with the grant key. Only the backend holds that key, so a browser cannot
+ * warm, pin or inspect a tenant.
+ */
+export function mintTenantOrder(claims, key) {
+    const { action } = claims;
+    if (!TENANT_ACTIONS.has(action))
+        refuse(`action ${JSON.stringify(action)} is not warm, pin, unpin, state or evict`);
+    const orderId = claims.orderId ?? randomBytes(16).toString("base64url");
+    if (!/^[A-Za-z0-9_-]{16,64}$/u.test(orderId))
+        refuse("orderId must be 16 to 64 base64url characters");
+    const issued = unsigned("issuedAtUnixSeconds", claims.issuedAtUnixSeconds);
+    const expires = unsigned("expiresAtUnixSeconds", claims.expiresAtUnixSeconds);
+    if (expires <= issued || expires - issued > MAX_TENANT_ORDER_LIFETIME_SECONDS)
+        refuse(`a tenant order is valid for 1 to ${String(MAX_TENANT_ORDER_LIFETIME_SECONDS)} s`);
+    const payload = [
+        `"version":1`,
+        `"keyId":${JSON.stringify(keyId(claims.keyId))}`,
+        `"audience":${JSON.stringify(audience(claims.audience))}`,
+        `"orderId":${JSON.stringify(orderId)}`,
+        `"action":${JSON.stringify(action)}`,
+        `"tenant":${attributeValue("tenant", claims.tenant)}`,
+        `"issuedAtUnixSeconds":${String(issued)}`,
+        `"expiresAtUnixSeconds":${String(expires)}`,
+    ].join(",");
+    return signUnder(TENANT_ORDER_SIGNING_DOMAIN, Buffer.from(`{${payload}}`, "utf8"), key);
+}
+//# sourceMappingURL=mint.js.map

package/dist/mint.js.map

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

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@calque/grant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Signs Calque dataset grants and tenant orders from a Node backend, and creates the signing key; calque-grant is its command line.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/calque-sh/calque",
+    "directory": "client/packages/grant"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
+  },
+  "type": "module",
+  "bin": {
+    "calque-grant": "./bin/calque-grant.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "devDependencies": {
+    "@eslint/js": "^9.31.0",
+    "@types/node": "^24.0.0",
+    "eslint": "^9.31.0",
+    "jiti": "^2.7.0",
+    "prettier": "^3.6.0",
+    "typescript": "^5.8.0",
+    "typescript-eslint": "^8.38.0",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "format": "prettier --write .",
+    "lint": "eslint . --max-warnings 0 && prettier --check .",
+    "test": "vitest run",
+    "typecheck": "../../../node_modules/.bin/tsc -p tsconfig.json --noEmit"
+  }
 }