@grantex/gemma

Offline authorization adapter for Google Gemma on-device AI agents -- issue consent bundles online, verify grant tokens and enforce scopes entirely offline, and sync tamper-evident audit logs back to Grantex cloud when connectivity returns.

Homepage | Docs | API Reference | GitHub | Sign Up Free

What is @grantex/gemma?

Google Gemma 4 is a family of lightweight, open-weight models designed to run directly on edge devices -- phones, Raspberry Pis, Jetson boards, and embedded hardware. When an AI agent built on Gemma operates in the field, it often loses internet connectivity for hours or days at a time. Traditional cloud-based authorization (OAuth 2.0, API-key checks) simply stops working the moment the network drops.

@grantex/gemma solves this by bringing the Grantex delegated authorization protocol to offline environments. While the device is still online, it fetches a consent bundle -- a self-contained package containing a signed grant token, a JWKS snapshot for signature verification, and an Ed25519 key pair for audit signing. Once offline, the agent verifies tokens, enforces scopes, and logs every action to a tamper-evident, hash-chained audit log -- all without a single network call.

The lifecycle follows three phases: (1) Online bundle issue -- fetch the consent bundle and persist it with AES-256-GCM encryption, (2) Offline verify + audit -- verify JWTs, enforce scopes, and sign audit entries locally, and (3) Sync -- when connectivity returns, upload the audit log to the Grantex cloud with batched retry. This package also ships framework adapters for Google ADK and LangChain, so you can wrap any tool with offline authorization in a single function call.

Installation

npm install @grantex/gemma

yarn add @grantex/gemma

pnpm add @grantex/gemma

Quick Start

Phase 1 -- Online: Issue a Consent Bundle

import { createConsentBundle, storeBundle } from '@grantex/gemma';

// While the device is online, request a consent bundle from Grantex
const bundle = await createConsentBundle({
  apiKey: process.env.GRANTEX_API_KEY!,
  agentId: 'agent_gemma_01',
  userId: 'user_alice',
  scopes: ['calendar:read', 'email:send'],
  offlineTTL: '72h', // bundle is valid for 72 hours offline
});

// Persist the bundle to encrypted local storage (AES-256-GCM)
await storeBundle(bundle, '/data/grantex/bundle.enc', process.env.ENCRYPTION_KEY!);

Phase 2 -- Offline: Verify Tokens and Log Actions

import {
  loadBundle,
  createOfflineVerifier,
  createOfflineAuditLog,
  enforceScopes,
} from '@grantex/gemma';

// Load the bundle from encrypted storage
const bundle = await loadBundle('/data/grantex/bundle.enc', process.env.ENCRYPTION_KEY!);

// Create the offline verifier using the embedded JWKS snapshot
const verifier = createOfflineVerifier({
  jwksSnapshot: bundle.jwksSnapshot,
  requireScopes: ['calendar:read'],
  maxDelegationDepth: 2,
});

// Verify the grant token entirely on-device -- no network call
const grant = await verifier.verify(bundle.grantToken);
console.log(grant.agentDID, grant.scopes, grant.expiresAt);

// Create a hash-chained, Ed25519-signed offline audit log
const auditLog = createOfflineAuditLog({
  signingKey: bundle.offlineAuditKey,
  logPath: '/data/grantex/audit.jsonl',
});

// Log every action the agent performs
await auditLog.append({
  action: 'tool:read_calendar',
  agentDID: grant.agentDID,
  grantId: grant.grantId,
  scopes: grant.scopes,
  result: 'success',
  metadata: { eventCount: 5 },
});

Phase 3 -- Online: Sync Audit Log

import { syncAuditLog } from '@grantex/gemma';

// When connectivity returns, sync all un-uploaded entries
const result = await syncAuditLog(auditLog, {
  endpoint: bundle.syncEndpoint,
  apiKey: process.env.GRANTEX_API_KEY!,
  bundleId: bundle.bundleId,
  batchSize: 100, // entries per HTTP request
});

console.log(`Synced ${result.syncedCount} entries`);
if (result.hasErrors) console.error(result.errors);

Architecture

  ONLINE (Phase 1)                OFFLINE (Phase 2)              ONLINE (Phase 3)
  ─────────────────               ─────────────────              ─────────────────
  Grantex Cloud                   On-Device (Gemma 4)            Grantex Cloud
  ┌──────────────┐                ┌──────────────────┐           ┌──────────────┐
  │ POST /v1/    │  consent       │ loadBundle()      │  sync    │ POST /v1/    │
  │ consent-     │  bundle        │   ▼ JWKS Snapshot  │  audit   │ audit/       │
  │ bundles      │ ──────────►    │   ▼ verify(token)  │ ──────►  │ offline-sync │
  └──────────────┘                │   ▼ enforceScopes()│          └──────────────┘
       AES-256-GCM ◄──────────   │   ▼ auditLog       │
       encrypted on disk          │   ▼ Hash-Chained   │
                                  │     (.jsonl)       │
                                  └──────────────────┘

API Reference

Verifier

createOfflineVerifier(options): OfflineVerifier

Create an offline JWT verifier that validates Grantex grant tokens using a pre-fetched JWKS snapshot. No network call is made during verification.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | jwksSnapshot | JWKSSnapshot | required | Pre-fetched JWKS keys from the consent bundle | | clockSkewSeconds | number | 30 | Clock skew tolerance in seconds | | requireScopes | string[] | -- | Scopes that must be present in every verified token | | maxDelegationDepth | number | -- | Maximum delegation chain depth (inclusive) | | onScopeViolation | 'throw' \| 'log' | 'throw' | Behaviour when a scope check fails |

Returns an OfflineVerifier with a single method:

• verify(token: string): Promise<VerifiedGrant> -- verify a JWT and return the decoded grant.

VerifiedGrant fields:

| Field | Type | Description | |-------|------|-------------| | agentDID | string | Agent's DID (agt JWT claim) | | principalDID | string | User who authorized the grant (sub claim) | | scopes | string[] | Granted scopes (scp claim) | | expiresAt | Date | Token expiry | | jti | string | Unique token ID (jti claim) | | grantId | string | Grant record ID (grnt claim, falls back to jti) | | depth | number | Delegation depth (0 = root grant) |

Example:

const verifier = createOfflineVerifier({
  jwksSnapshot: bundle.jwksSnapshot,
  requireScopes: ['files:read'],
  clockSkewSeconds: 60,
  maxDelegationDepth: 3,
});

const grant = await verifier.verify(bundle.grantToken);
console.log(grant.agentDID);   // 'did:web:agent.example'
console.log(grant.scopes);     // ['files:read', 'files:write']
console.log(grant.grantId);    // 'grnt_01J...'

enforceScopes(grantScopes, requiredScopes): void

Throws ScopeViolationError if any required scope is missing from the grant.

hasScope(grantScopes, scope): boolean

Check whether a single scope is present. Returns boolean.

Consent Bundles

createConsentBundle(options): Promise<ConsentBundle>

Request a consent bundle from the Grantex API. This call requires network connectivity -- the returned bundle is then used for all offline operations.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Grantex developer API key | | baseUrl | string | https://api.grantex.dev | API base URL | | agentId | string | required | Agent requesting the bundle | | userId | string | required | End-user / principal granting consent | | scopes | string[] | required | Requested scopes | | offlineTTL | string | '72h' | Offline validity period (e.g. '24h', '7d') | | offlineAuditKeyAlgorithm | string | 'Ed25519' | Signing algorithm for audit entries | | storage | string | -- | Storage backend: 'encrypted-file', 'keychain', 'secure-enclave' | | storagePath | string | -- | File path when storage is 'encrypted-file' |

ConsentBundle fields:

| Field | Type | Description | |-------|------|-------------| | bundleId | string | Unique bundle identifier | | grantToken | string | Grantex grant token (RS256 JWT) | | jwksSnapshot | JWKSSnapshot | JWKS keys for offline verification | | offlineAuditKey | { publicKey, privateKey, algorithm } | Ed25519 key pair for signing audit entries | | checkpointAt | number | Unix-ms timestamp of last successful cloud sync | | syncEndpoint | string | URL for syncing audit entries back to cloud | | offlineExpiresAt | string | ISO-8601 timestamp after which offline operation is disallowed |

Example:

const bundle = await createConsentBundle({
  apiKey: 'gx_live_...',
  agentId: 'agent_gemma_field',
  userId: 'usr_01J...',
  scopes: ['sensor:read', 'actuator:write'],
  offlineTTL: '7d',
});

storeBundle(bundle, path, encryptionKey): Promise<void>

Encrypt and write a bundle to disk using AES-256-GCM. File format: [12-byte IV][16-byte auth-tag][ciphertext]. The encryption key is SHA-256-hashed to derive a 32-byte AES key, so any passphrase length works.

loadBundle(path, encryptionKey): Promise<ConsentBundle>

Read and decrypt a bundle from disk. Throws BundleTamperedError if decryption or integrity check fails.

shouldRefresh(bundle): boolean

Returns true when less than 20% of the bundle's total offline TTL remains. Call this proactively when connectivity is available.

refreshBundle(bundle, apiKey, baseUrl?): Promise<ConsentBundle>

Refresh an expiring bundle via the Grantex API. Returns a new bundle with extended offlineExpiresAt, fresh JWKS snapshot, and rotated audit keys.

if (shouldRefresh(bundle)) {
  const refreshed = await refreshBundle(bundle, process.env.GRANTEX_API_KEY!);
  await storeBundle(refreshed, '/data/grantex/bundle.enc', process.env.ENCRYPTION_KEY!);
}

Audit Log

createOfflineAuditLog(options): OfflineAuditLog

Create an append-only, Ed25519-signed, hash-chained audit log backed by a JSONL file. Every entry is cryptographically linked to the previous one, forming a tamper-evident chain.

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | signingKey | { publicKey, privateKey, algorithm } | required | Ed25519 key pair (from consent bundle) | | logPath | string | required | Path to the JSONL log file | | maxSizeMB | number | 50 | Max file size in MB before rotation | | rotateOnSize | boolean | true | Enable automatic size-based rotation |

Methods:

| Method | Signature | Description | |--------|-----------|-------------| | append | (entry: AuditEntry) => Promise<SignedAuditEntry> | Append a new signed, hash-chained entry | | entries | () => Promise<SignedAuditEntry[]> | Read all entries from the log file | | unsyncedCount | () => Promise<number> | Count entries not yet synced to cloud | | markSynced | (upToSeq: number) => Promise<void> | Mark entries as synced up to a sequence number |

SignedAuditEntry fields:

| Field | Type | Description | |-------|------|-------------| | seq | number | Monotonically increasing sequence number | | timestamp | string | ISO-8601 timestamp of the entry | | action | string | Action performed (e.g. 'tool:read_calendar') | | agentDID | string | Agent that performed the action | | grantId | string | Grant under which the action was authorized | | scopes | string[] | Scopes the grant carried at the time | | result | string | Outcome: 'success', 'auth_failure', 'scope_violation', 'execution_error' | | metadata | Record<string, unknown>? | Optional structured metadata | | prevHash | string | SHA-256 hash of the previous entry (genesis: '0000000000000000') | | hash | string | SHA-256 hash of this entry | | signature | string | Ed25519 signature of the hash (hex-encoded) |

syncAuditLog(auditLog, options): Promise<SyncResult>

POST un-synced audit entries to the Grantex cloud in batches with automatic retry (3 attempts, exponential back-off).

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | required | Sync endpoint URL (from bundle.syncEndpoint) | | apiKey | string | required | Developer API key | | bundleId | string | required | Consent bundle ID linking entries to an offline session | | batchSize | number | 100 | Entries per HTTP request |

Returns SyncResult with syncedCount, hasErrors, and errors[].

computeEntryHash(entry): string

Compute the SHA-256 hash of an audit entry. Input: seq|timestamp|action|agentDID|grantId|scopes|result|metadata|prevHash.

verifyChain(entries): { valid: boolean; brokenAt?: number }

Verify the integrity of an ordered sequence of entries. Checks hash recomputation, prevHash linkage, and sequence continuity.

verifyEntrySignature(entry, publicKey): boolean

Verify the Ed25519 signature of a single audit entry.

import { verifyChain, verifyEntrySignature } from '@grantex/gemma';

const { valid, brokenAt } = verifyChain(await auditLog.entries());
const sigValid = verifyEntrySignature(entry, bundle.offlineAuditKey.publicKey);

Adapters

withGrantexAuthADK(tool, options) / withGrantexAuthLangChain(tool, options)

Wrap a Google ADK FunctionTool or LangChain StructuredTool with Grantex offline authorization. Before the tool executes, the grant token is verified and scopes are enforced. After execution, an audit entry is appended automatically.

import { withGrantexAuthADK, withGrantexAuthLangChain } from '@grantex/gemma';

// Google ADK -- wraps tools with `func` or `run` methods
const protectedAdkTool = withGrantexAuthADK(myAdkTool, {
  verifier, auditLog,
  requiredScopes: ['calendar:read'],
  grantToken: bundle.grantToken,
});

// LangChain -- wraps tools with `_call` or `invoke` methods
const protectedLcTool = withGrantexAuthLangChain(myLangChainTool, {
  verifier, auditLog,
  requiredScopes: ['email:read'],
  grantToken: bundle.grantToken,
});

Both adapters accept the same options:

| Option | Type | Description | |--------|------|-------------| | verifier | OfflineVerifier | Offline verifier instance | | auditLog | OfflineAuditLog | Offline audit log instance | | requiredScopes | string[] | Scopes required to invoke this tool | | grantToken | string | Grantex grant token (JWT) |

Type Definitions

interface JWKSSnapshot {
  keys: JWK[];        // JWK key objects (must include kid and alg)
  fetchedAt: string;   // ISO-8601 when snapshot was fetched
  validUntil: string;  // ISO-8601 after which snapshot should be refreshed
}

interface ConsentBundle {
  bundleId: string;
  grantToken: string;                   // RS256 JWT
  jwksSnapshot: JWKSSnapshot;
  offlineAuditKey: { publicKey: string; privateKey: string; algorithm: string };
  checkpointAt: number;                 // Unix-ms timestamp
  syncEndpoint: string;
  offlineExpiresAt: string;             // ISO-8601
}

interface VerifiedGrant {
  agentDID: string;      principalDID: string;
  scopes: string[];      expiresAt: Date;
  jti: string;           grantId: string;       depth: number;
}

interface SignedAuditEntry {
  seq: number;           timestamp: string;      action: string;
  agentDID: string;      grantId: string;        scopes: string[];
  result: string;        metadata?: Record<string, unknown>;
  prevHash: string;      hash: string;           signature: string;
}

interface SyncResult {
  syncedCount: number;   hasErrors: boolean;     errors: string[];
}

// Errors -- all extend GrantexAuthError (which extends Error with a `code` property)
class OfflineVerificationError  { code: string }  // VERIFICATION_FAILED, MALFORMED_TOKEN,
                                                   // BLOCKED_ALGORITHM, MISSING_KID, KID_NOT_FOUND,
                                                   // FUTURE_IAT, DELEGATION_DEPTH_EXCEEDED
class ScopeViolationError       { requiredScopes: string[]; grantScopes: string[] }
class TokenExpiredError          { expiredAt: Date }
class BundleTamperedError       { /* code: BUNDLE_TAMPERED */ }
class HashChainError            { brokenAt: number }

Security

What offline verification guarantees:

• Signature integrity -- every token is verified against a pre-fetched JWKS snapshot using RS256.
• Scope enforcement -- required scopes are checked on every verification; agents cannot escalate permissions.
• Tamper-evident audit trail -- every entry is SHA-256 hash-chained and Ed25519-signed. verifyChain() detects any modification.
• Encrypted storage -- bundles are stored with AES-256-GCM (12-byte IV, 16-byte auth-tag). The encryption key is SHA-256-hashed to derive the 32-byte AES key.

What it does NOT guarantee:

• Real-time revocation -- if a grant is revoked in the cloud while the device is offline, the local verifier continues to accept the token until expiry or offlineExpiresAt. This is an inherent trade-off of offline operation.
• Clock accuracy -- verification depends on the device clock. Use clockSkewSeconds to account for drift.

Additional security details:

• Blocked algorithms -- none and HS256 are explicitly blocked to prevent signature bypass and symmetric-key confusion attacks. Only RS256 tokens are accepted.
• Hash chain -- each entry hash is computed from seq|timestamp|action|agentDID|grantId|scopes|result|metadata|prevHash. Genesis hash: '0000000000000000'.
• Ed25519 audit signing -- every entry's hash is signed with the private key from the consent bundle. Verify with verifyEntrySignature().

Platform Compatibility

@grantex/gemma runs anywhere Node.js 18+ is available:

| Platform | Requirement | Notes | |----------|-------------|-------| | Raspberry Pi 5 | Node.js 18+ (ARM64) | 3.2ms avg verification | | Android | React Native / Termux | 1.8ms avg verification | | iOS | JavaScriptCore / embedded V8 | 1.8ms avg verification | | NVIDIA Jetson | Node.js 18+ (ARM64) | 1.1ms avg verification | | Desktop | Node.js 18+ (x64/ARM64) | < 1ms avg verification | | Edge servers | Cloudflare Workers, Deno Deploy | < 1ms avg verification |

The package is pure ESM ("type": "module" in your package.json, or use dynamic import()).

Error Handling

All errors extend GrantexAuthError and include a machine-readable code property:

import {
  TokenExpiredError, ScopeViolationError,
  OfflineVerificationError, BundleTamperedError, HashChainError,
} from '@grantex/gemma';

try {
  const grant = await verifier.verify(token);
  enforceScopes(grant.scopes, ['files:write']);
} catch (err) {
  if (err instanceof TokenExpiredError) {
    console.error(`Token expired at ${err.expiredAt.toISOString()}`);
  } else if (err instanceof ScopeViolationError) {
    console.error(`Missing: required ${err.requiredScopes}, got ${err.grantScopes}`);
  } else if (err instanceof OfflineVerificationError) {
    console.error(`[${err.code}]: ${err.message}`);
  } else if (err instanceof BundleTamperedError) {
    console.error('Bundle integrity check failed');
  } else if (err instanceof HashChainError) {
    console.error(`Chain broken at entry ${err.brokenAt}`);
  }
}

Testing

49 tests across 6 test files (offline verifier, scope enforcer, consent bundles, hash chain, audit log, security):

npm test            # run all tests
npm run test:watch  # watch mode
npm run typecheck   # type checking only

Framework Integrations

| Framework | Adapter | Import | |-----------|---------|--------| | Google ADK | withGrantexAuthADK | import { withGrantexAuthADK } from '@grantex/gemma' | | LangChain | withGrantexAuthLangChain | import { withGrantexAuthLangChain } from '@grantex/gemma' |

Both adapters automatically handle token verification, scope enforcement, and audit logging. See the Adapters section above for full usage examples.

Examples

| Example | Platform | Description | |---------|----------|-------------| | gemma-raspberry-pi | Raspberry Pi 5 | Python agent with bundle setup, offline operation, and audit sync | | gemma-android-kotlin | Android | Kotlin app with offline auth manager and audit logging | | gemma-ios-swift | iOS | Swift package with offline verifier and consent bundle manager |

Troubleshooting

Token verification fails offline

The JWKS snapshot embedded in your consent bundle may have expired. Check the validUntil field:

import { isSnapshotExpired } from '@grantex/gemma';

if (isSnapshotExpired(bundle.jwksSnapshot)) {
  // Snapshot expired -- refresh the bundle when connectivity is available
}

Also verify the offlineExpiresAt on the bundle itself has not passed.

BundleTamperedError when loading

This means decryption failed. Common causes:

• Wrong encryption key -- ensure you pass the same key used during storeBundle().
• Corrupted file -- the bundle file was partially written or modified on disk.
• File too short -- the file must contain at least 28 bytes (12-byte IV + 16-byte auth-tag).

Hash chain broken

verifyChain() returns { valid: false, brokenAt: N } when entries have been modified outside the audit log. This is expected tamper-detection behaviour. Do not manually edit the JSONL audit file.

Clock skew errors

If verification fails with FUTURE_IAT or tokens appear expired prematurely, increase the clock skew tolerance:

const verifier = createOfflineVerifier({
  jwksSnapshot: bundle.jwksSnapshot,
  clockSkewSeconds: 120, // allow up to 2 minutes of drift
});

Related Packages

| Package | Description | |---------|-------------| | @grantex/sdk | TypeScript SDK for the Grantex protocol | | grantex | Python SDK | | grantex-adk | Google ADK integration (Python) | | @grantex/langchain | LangChain integration | | @grantex/mcp | MCP server for Claude Desktop / Cursor / Windsurf | | @grantex/cli | Command-line tool | | @grantex/express | Express.js middleware | | @grantex/gateway | Reverse-proxy gateway |

Contributing

See CONTRIBUTING.md for guidelines on setting up the development environment, running tests, and submitting pull requests.

License

Apache 2.0