@indigoai-us/hq-cli 5.43.0 → 5.44.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.44.0]
+
+### Added
+
+- **`hq publish --as <handle>` (alias `--on-behalf <handle>`) — publish on
+  behalf of a seeded creator.** Lets HQ staff publish a pack attributed to a
+  seeded, unclaimed creator (e.g. an upstream OSS author ported into
+  `hq-packages`) instead of to themselves. Pairs with the staff-gated
+  `publishAsHandle` capability in hq-pro (#508): the server requires staff
+  (`@getindigo.ai`), restricts attribution to unclaimed creators, and is
+  gated by an off-by-default kill-switch. Without `--as`, publish behavior is
+  unchanged (normal verified-creator self-publish). On the `--as` path the CLI
+  leaves the manifest author intact (the server is authoritative for
+  attribution) rather than stamping the caller.
+
+### Fixed
+
+- **On-behalf publish authenticates with the ID token, not the access token.**
+  The server's staff gate reads the `email` claim, which Cognito puts on the
+  id_token only — the access token returns `403 NO_EMAIL_CLAIM`. `--as` now
+  sends the id_token (new `ensureCognitoIdToken`); normal self-publish keeps
+  using the access token.
+
 ## [5.41.0]
 
 ### Added

package/dist/commands/publish.d.ts

@@ -144,14 +144,27 @@ export interface ListingRequest {
     summary?: string;
     contributes?: string;
     creatorHandle?: string;
+    /**
+     * OPTIONAL staff-gated publish-on-behalf target handle (`hq publish --as
+     * <handle>`). When set, the server attributes the listing to the seeded,
+     * UNCLAIMED creator with this handle instead of the caller — but only if the
+     * caller is staff (`@getindigo.ai`) and the server has the capability enabled.
+     */
+    publishAsHandle?: string;
     /** Base64-encoded gzip pack tarball (pack.tar.gz bytes). */
     tarball: string;
 }
 export interface PublishDeps {
     /** Returns the cached idToken, or null/expired if not logged in. */
     loadIdToken: () => string | null;
-    /** Returns a non-interactive access token. */
+    /** Returns a non-interactive access token (normal self-publish). */
     getAccessToken: () => Promise<string>;
+    /**
+     * Returns a non-interactive ID token. Required for an on-behalf publish
+     * (`--as <handle>`): the server's staff gate reads the `email` claim, which is
+     * on the id_token only — the access token returns 403 NO_EMAIL_CLAIM.
+     */
+    getIdToken: () => Promise<string>;
     /**
      * POSTs the listing as a JSON body to `/v1/listings` and returns the parsed
      * { status, body }. `tarball` is the BASE64-encoded gzip pack bytes — the
@@ -181,6 +194,8 @@ export interface PublishResult {
  * success notice; throws (uploading nothing) on logged-out or validation
  * failure.
  */
-export declare function runPublish(targetPath: string, deps: PublishDeps): Promise<PublishResult>;
+export declare function runPublish(targetPath: string, deps: PublishDeps, opts?: {
+    publishAsHandle?: string;
+}): Promise<PublishResult>;
 export declare function registerPublishCommand(program: Command): void;
 //# sourceMappingURL=publish.d.ts.map

package/dist/commands/publish.js

@@ -28,7 +28,7 @@
  *   - manifest.ts (modules.yaml read/write for provenance)
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9b60d0b2-fea1-50bd-8c4e-e39163c38e30")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e2f6607e-188c-57f9-beba-a81488d15225")}catch(e){}}();
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -36,7 +36,7 @@ import * as yaml from 'js-yaml';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
-import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { ensureCognitoToken, ensureCognitoIdToken } from '../utils/cognito-session.js';
 import { vaultApiFetch } from '../utils/vault-api.js';
 import { validateManifest } from './pack-install.js';
 import { findHqRoot, readManifest, writeManifest } from '../utils/manifest.js';
@@ -237,6 +237,14 @@ export function buildListingNotice(status, body, packName, packVersion) {
         throw new Error(`${packName}@${packVersion} is already published (duplicate version). ` +
             `Bump the version in package.yaml and re-run \`hq publish\`.`);
     }
+    if (status === 400) {
+        const code = typeof body.code === 'string' ? body.code : '';
+        if (code === 'ON_BEHALF_DISABLED') {
+            throw new Error('Publishing on behalf of another creator is not enabled on this server. ' +
+                'Ask an HQ admin to turn on the on-behalf capability, or publish without `--as`.');
+        }
+        // Any other 400 falls through to the generic non-2xx handler below.
+    }
     if (status === 401 || status === 403) {
         const code = typeof body.code === 'string' ? body.code : '';
         if (code === 'NOT_VERIFIED_CREATOR') {
@@ -244,6 +252,13 @@ export function buildListingNotice(status, body, packName, packVersion) {
                 'Run `hq creators apply --reason "..."` to request verified-creator access; ' +
                 'an Indigo admin will review it.');
         }
+        if (code === 'FORBIDDEN' || code === 'NO_EMAIL_CLAIM') {
+            // The staff gate rejected an on-behalf (`--as`) publish — only the normal
+            // self-publish path returns NOT_VERIFIED_CREATOR, so these codes here mean
+            // a non-staff caller tried to publish as someone else.
+            throw new Error('Only HQ staff can publish on behalf of another creator (`--as`). ' +
+                'Re-run without `--as` to publish as yourself.');
+        }
         throw new Error('Not authorized to publish — run `hq login` and ensure your creator account is verified.');
     }
     if (status < 200 || status >= 300) {
@@ -263,13 +278,16 @@ export function buildListingNotice(status, body, packName, packVersion) {
  * success notice; throws (uploading nothing) on logged-out or validation
  * failure.
  */
-export async function runPublish(targetPath, deps) {
+export async function runPublish(targetPath, deps, opts = {}) {
     // 1. Logged-in gate — refuse BEFORE any packing/upload.
     const idToken = deps.loadIdToken();
     if (!idToken) {
         throw new Error('Not logged in — run `hq login` before publishing. Nothing was uploaded.');
     }
     const author = resolveAuthor(peekIdToken(idToken));
+    const publishAsHandle = typeof opts.publishAsHandle === 'string' && opts.publishAsHandle.length > 0
+        ? opts.publishAsHandle
+        : undefined;
     // Resolve a payload dir. We stamp/validate against a temp copy so we never
     // mutate the user's working tree's package.yaml.
     const absTarget = path.resolve(process.cwd(), targetPath);
@@ -285,7 +303,14 @@ export async function runPublish(targetPath, deps) {
         if (!fs.existsSync(path.join(payloadDir, 'package.yaml'))) {
             throw new Error(`package.yaml missing from ${absTarget} — nothing was uploaded.`);
         }
-        stampAuthorIntoPackage(payloadDir, author);
+        // On the on-behalf path (`--as <handle>`) the SERVER is authoritative for
+        // attribution (it resolves the target creator by handle and ignores the
+        // manifest/stamped author), so we must NOT overwrite the manifest's author
+        // with the CALLER's identity — the manifest already names the target
+        // creator. Stamp the caller only on the normal self-publish path.
+        if (!publishAsHandle) {
+            stampAuthorIntoPackage(payloadDir, author);
+        }
         // 3. Validate with the canonical 10-rule validator. Throws on any failure;
         //    we have uploaded nothing at this point.
         const pkg = validateManifest(payloadDir, deps.hqVersion);
@@ -293,7 +318,13 @@ export async function runPublish(targetPath, deps) {
         //    JSON.parses the body, so we send the gzip tarball base64-encoded
         //    inside a JSON listing request (NOT a raw octet-stream body).
         const tarballBytes = tarballPayload(payloadDir);
-        const token = await deps.getAccessToken();
+        // On-behalf publishes are staff-gated server-side and the staff gate reads
+        // the id_token `email` claim — send the ID token, not the access token
+        // (which has no email and would 403 NO_EMAIL_CLAIM). Normal self-publish
+        // continues to use the access token.
+        const token = publishAsHandle
+            ? await deps.getIdToken()
+            : await deps.getAccessToken();
         const listing = {
             type: inferListingType(pkg),
             name: pkg.name,
@@ -301,9 +332,12 @@ export async function runPublish(targetPath, deps) {
             version: pkg.version,
             summary: pkg.description,
             contributes: summarizeContributes(pkg.contributes) || undefined,
-            // Server prefers the caller's claimed creator handle, but we stamp our
-            // resolved handle as a backwards-compat fallback.
-            creatorHandle: author.handle,
+            // On-behalf: send the target handle so the body is self-describing (the
+            // server is authoritative for attribution either way). Normal: our
+            // resolved handle is a backwards-compat fallback under the server's
+            // claimed-handle lookup.
+            creatorHandle: publishAsHandle ?? author.handle,
+            ...(publishAsHandle ? { publishAsHandle } : {}),
             tarball: Buffer.from(tarballBytes).toString('base64'),
         };
         const { status, body } = await deps.upload({ token, listing });
@@ -326,8 +360,12 @@ export function registerPublishCommand(program) {
     program
         .command('publish <path>')
         .description('Package a skill/worker pack and submit it to the HQ marketplace (POST /v1/listings).')
-        .action(async (targetPath) => {
+        .option('--as <handle>', 'Publish on behalf of a seeded, unclaimed creator by handle (HQ staff only). ' +
+        'The listing is attributed to that creator instead of you.')
+        .option('--on-behalf <handle>', 'Alias for --as.')
+        .action(async (targetPath, options) => {
         try {
+            const publishAsHandle = options.as ?? options.onBehalf;
             const hqRoot = findHqRoot();
             const result = await runPublish(targetPath, {
                 loadIdToken: () => {
@@ -337,6 +375,7 @@ export function registerPublishCommand(program) {
                     return cached.idToken;
                 },
                 getAccessToken: () => ensureCognitoToken({ interactive: false }),
+                getIdToken: () => ensureCognitoIdToken({ interactive: false }),
                 upload: async ({ token, listing }) => {
                     // JSON body (application/json) — the deployed handler JSON.parses
                     // the body and base64-decodes `listing.tarball`. vaultApiFetch
@@ -352,7 +391,7 @@ export function registerPublishCommand(program) {
                 },
                 hqRoot,
                 hqVersion: readHqVersion(hqRoot),
-            });
+            }, { publishAsHandle });
             console.log(chalk.green(result.notice));
             // Only print the locally-resolved author as a fallback when the server
             // did NOT return its own resolved handle (already in the notice).
@@ -367,4 +406,4 @@ export function registerPublishCommand(program) {
     });
 }
 //# sourceMappingURL=publish.js.map
-//# debugId=9b60d0b2-fea1-50bd-8c4e-e39163c38e30
+//# debugId=e2f6607e-188c-57f9-beba-a81488d15225

package/dist/utils/cognito-session.d.ts

@@ -83,6 +83,20 @@ export declare const DEFAULT_HQ_ROOT: string;
 export declare function ensureCognitoToken(options?: {
     interactive?: boolean;
 }): Promise<string>;
+/**
+ * Return a non-expired Cognito **ID** token (mirrors `ensureCognitoToken`'s
+ * refresh/login flow but yields the id_token, not the access token).
+ *
+ * Staff-gated vault-API routes (`assertStaffCaller`) read the `email` claim,
+ * which Cognito puts on the ID token ONLY — the access token has no `email`, so
+ * sending it returns `403 NO_EMAIL_CLAIM`. Callers performing a staff action
+ * (e.g. `hq publish --as <handle>`) MUST send the ID token. For machine
+ * identities the vault API already authenticates with the ID token, so this is
+ * identical to `ensureCognitoToken` there.
+ */
+export declare function ensureCognitoIdToken(options?: {
+    interactive?: boolean;
+}): Promise<string>;
 /**
  * The CLI's own ClientInfo. Resolved once at module load so every VaultClient
  * built in this process stamps the same name/version onto its requests.

package/dist/utils/cognito-session.js

@@ -19,7 +19,7 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="783fe478-9e12-55a7-a3d8-241ea2cf5886")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="21e260f0-50fd-54c7-944a-c15630c42f3e")}catch(e){}}();
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -269,6 +269,48 @@ export async function ensureCognitoToken(options = {}) {
     const tokens = await browserLogin(DEFAULT_COGNITO);
     return tokens.accessToken;
 }
+/**
+ * Return a non-expired Cognito **ID** token (mirrors `ensureCognitoToken`'s
+ * refresh/login flow but yields the id_token, not the access token).
+ *
+ * Staff-gated vault-API routes (`assertStaffCaller`) read the `email` claim,
+ * which Cognito puts on the ID token ONLY — the access token has no `email`, so
+ * sending it returns `403 NO_EMAIL_CLAIM`. Callers performing a staff action
+ * (e.g. `hq publish --as <handle>`) MUST send the ID token. For machine
+ * identities the vault API already authenticates with the ID token, so this is
+ * identical to `ensureCognitoToken` there.
+ */
+export async function ensureCognitoIdToken(options = {}) {
+    const interactive = options.interactive ?? true;
+    if (isMachineIdentity()) {
+        const machine = await getValidMachineTokens(DEFAULT_COGNITO);
+        return machine.idToken;
+    }
+    const cached = loadCachedTokens();
+    if (cached && !isExpiring(cached, 120)) {
+        return cached.idToken;
+    }
+    if (cached) {
+        try {
+            if (interactive) {
+                console.error(chalk.dim("  Refreshing expiring HQ session..."));
+            }
+            const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+            return refreshed.idToken;
+        }
+        catch (err) {
+            if (interactive) {
+                console.error(chalk.dim(`  Refresh failed (${err instanceof Error ? err.message : err}), falling back to browser login`));
+            }
+        }
+    }
+    if (!interactive) {
+        throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
+    }
+    console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
+    const tokens = await browserLogin(DEFAULT_COGNITO);
+    return tokens.idToken;
+}
 /**
  * The CLI's own ClientInfo. Resolved once at module load so every VaultClient
  * built in this process stamps the same name/version onto its requests.
@@ -328,4 +370,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=783fe478-9e12-55a7-a3d8-241ea2cf5886
+//# debugId=21e260f0-50fd-54c7-944a-c15630c42f3e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.43.0",
+  "version": "5.44.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/publish.test.ts

@@ -171,6 +171,16 @@ describe('buildListingNotice', () => {
       buildListingNotice(403, { code: 'NOT_VERIFIED_CREATOR' }, 'hq-pack-demo', '1.0.0'),
     ).toThrow(/hq creators apply/i);
   });
+  it('maps a 400 ON_BEHALF_DISABLED to a clear "not enabled" message', () => {
+    expect(() =>
+      buildListingNotice(400, { code: 'ON_BEHALF_DISABLED' }, 'hq-pack-demo', '1.0.0'),
+    ).toThrow(/on behalf|not enabled/i);
+  });
+  it('maps a 403 staff-gate (FORBIDDEN) on an --as publish to a "staff only" message', () => {
+    expect(() =>
+      buildListingNotice(403, { code: 'FORBIDDEN' }, 'hq-pack-demo', '1.0.0'),
+    ).toThrow(/HQ staff|on behalf/i);
+  });
   it('surfaces a generic server error body', () => {
     expect(() => buildListingNotice(500, { error: 'boom' }, 'hq-pack-demo', '1.0.0')).toThrow(/boom/);
   });
@@ -321,6 +331,7 @@ function makeDeps(overrides: Partial<PublishDeps> = {}): {
   const deps: PublishDeps = {
     loadIdToken: () => fakeIdToken({ sub: 'usr_1', email: 'ada@b.com', name: 'Ada' }),
     getAccessToken: async () => 'access-token',
+    getIdToken: async () => 'id-token',
     upload: uploadSpy,
     hqRoot,
     hqVersion: null,
@@ -541,3 +552,99 @@ describe('runPublish', () => {
     expect(readManifest(hqRoot)).toBeNull();
   });
 });
+
+describe('runPublish — publish on behalf (--as <handle>)', () => {
+  it('sends publishAsHandle + attributes the body to the TARGET handle (not the caller)', async () => {
+    const packDir = writeValidPack(tmpRoot);
+    const { deps, uploadSpy } = makeDeps();
+
+    const result = await runPublish(packDir, deps, { publishAsHandle: 'garrytan' });
+
+    const call = uploadSpy.mock.calls[0][0];
+    const listing = call.listing as ListingRequest;
+    // The on-behalf signal is sent to the server.
+    expect(listing.publishAsHandle).toBe('garrytan');
+    // Body attribution is the TARGET handle, never the caller's resolved handle.
+    expect(listing.creatorHandle).toBe('garrytan');
+    expect(listing.creatorHandle).not.toBe(result.author.handle);
+    // CRITICAL: on-behalf must authenticate with the ID token (staff gate reads
+    // the email claim, which the access token lacks → would 403 NO_EMAIL_CLAIM).
+    expect(call.token).toBe('id-token');
+  });
+
+  it('on-behalf uses the ID token, normal publish uses the access token', async () => {
+    const packDir = writeValidPack(tmpRoot);
+    const onBehalf = makeDeps();
+    await runPublish(packDir, onBehalf.deps, { publishAsHandle: 'garrytan' });
+    expect(onBehalf.uploadSpy.mock.calls[0][0].token).toBe('id-token');
+
+    const normal = makeDeps();
+    await runPublish(packDir, normal.deps);
+    expect(normal.uploadSpy.mock.calls[0][0].token).toBe('access-token');
+  });
+
+  it('preserves a pre-existing manifest author (does NOT stamp the caller) on the --as path', async () => {
+    // A ported pack already names the upstream creator. With --as we must NOT
+    // overwrite that author with the publishing staff caller — validation must
+    // pass against the manifest's own author block.
+    const packDir = writeValidPack(tmpRoot, {
+      ...VALID_MANIFEST,
+      author: { uid: 'cmt_garrytan', handle: 'garrytan', displayName: 'Garry Tan' },
+    });
+    const { deps, uploadSpy } = makeDeps();
+
+    const result = await runPublish(packDir, deps, { publishAsHandle: 'garrytan' });
+
+    expect(uploadSpy).toHaveBeenCalledOnce();
+    expect(result.notice).toContain('pending_review');
+  });
+
+  it('normal publish (no --as) sends NO publishAsHandle and keeps caller attribution', async () => {
+    const packDir = writeValidPack(tmpRoot);
+    const { deps, uploadSpy } = makeDeps();
+
+    const result = await runPublish(packDir, deps);
+
+    const listing = uploadSpy.mock.calls[0][0].listing as ListingRequest;
+    expect(listing.publishAsHandle).toBeUndefined();
+    expect(listing.creatorHandle).toBe(result.author.handle);
+  });
+
+  it('an empty --as handle is treated as a normal self-publish', async () => {
+    const packDir = writeValidPack(tmpRoot);
+    const { deps, uploadSpy } = makeDeps();
+
+    await runPublish(packDir, deps, { publishAsHandle: '' });
+
+    const listing = uploadSpy.mock.calls[0][0].listing as ListingRequest;
+    expect(listing.publishAsHandle).toBeUndefined();
+  });
+
+  it('server kill-switch off (400 ON_BEHALF_DISABLED) surfaces a clear error', async () => {
+    const packDir = writeValidPack(tmpRoot);
+    const { deps } = makeDeps({
+      upload: vi.fn(async () => ({
+        status: 400,
+        body: { code: 'ON_BEHALF_DISABLED' } as Record<string, unknown>,
+      })),
+    });
+
+    await expect(
+      runPublish(packDir, deps, { publishAsHandle: 'garrytan' }),
+    ).rejects.toThrow(/on behalf|not enabled/i);
+  });
+
+  it('non-staff caller (403 FORBIDDEN) surfaces a "staff only" error', async () => {
+    const packDir = writeValidPack(tmpRoot);
+    const { deps } = makeDeps({
+      upload: vi.fn(async () => ({
+        status: 403,
+        body: { code: 'FORBIDDEN' } as Record<string, unknown>,
+      })),
+    });
+
+    await expect(
+      runPublish(packDir, deps, { publishAsHandle: 'garrytan' }),
+    ).rejects.toThrow(/HQ staff|on behalf/i);
+  });
+});

package/src/commands/publish.ts

@@ -36,7 +36,7 @@ import { execFileSync } from 'child_process';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
-import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { ensureCognitoToken, ensureCognitoIdToken } from '../utils/cognito-session.js';
 import { vaultApiFetch } from '../utils/vault-api.js';
 import { validateManifest } from './pack-install.js';
 import { findHqRoot, readManifest, writeManifest } from '../utils/manifest.js';
@@ -315,6 +315,16 @@ export function buildListingNotice(
         `Bump the version in package.yaml and re-run \`hq publish\`.`,
     );
   }
+  if (status === 400) {
+    const code = typeof body.code === 'string' ? body.code : '';
+    if (code === 'ON_BEHALF_DISABLED') {
+      throw new Error(
+        'Publishing on behalf of another creator is not enabled on this server. ' +
+          'Ask an HQ admin to turn on the on-behalf capability, or publish without `--as`.',
+      );
+    }
+    // Any other 400 falls through to the generic non-2xx handler below.
+  }
   if (status === 401 || status === 403) {
     const code = typeof body.code === 'string' ? body.code : '';
     if (code === 'NOT_VERIFIED_CREATOR') {
@@ -324,6 +334,15 @@ export function buildListingNotice(
           'an Indigo admin will review it.',
       );
     }
+    if (code === 'FORBIDDEN' || code === 'NO_EMAIL_CLAIM') {
+      // The staff gate rejected an on-behalf (`--as`) publish — only the normal
+      // self-publish path returns NOT_VERIFIED_CREATOR, so these codes here mean
+      // a non-staff caller tried to publish as someone else.
+      throw new Error(
+        'Only HQ staff can publish on behalf of another creator (`--as`). ' +
+          'Re-run without `--as` to publish as yourself.',
+      );
+    }
     throw new Error('Not authorized to publish — run `hq login` and ensure your creator account is verified.');
   }
   if (status < 200 || status >= 300) {
@@ -356,6 +375,13 @@ export interface ListingRequest {
   summary?: string;
   contributes?: string;
   creatorHandle?: string;
+  /**
+   * OPTIONAL staff-gated publish-on-behalf target handle (`hq publish --as
+   * <handle>`). When set, the server attributes the listing to the seeded,
+   * UNCLAIMED creator with this handle instead of the caller — but only if the
+   * caller is staff (`@getindigo.ai`) and the server has the capability enabled.
+   */
+  publishAsHandle?: string;
   /** Base64-encoded gzip pack tarball (pack.tar.gz bytes). */
   tarball: string;
 }
@@ -363,8 +389,14 @@ export interface ListingRequest {
 export interface PublishDeps {
   /** Returns the cached idToken, or null/expired if not logged in. */
   loadIdToken: () => string | null;
-  /** Returns a non-interactive access token. */
+  /** Returns a non-interactive access token (normal self-publish). */
   getAccessToken: () => Promise<string>;
+  /**
+   * Returns a non-interactive ID token. Required for an on-behalf publish
+   * (`--as <handle>`): the server's staff gate reads the `email` claim, which is
+   * on the id_token only — the access token returns 403 NO_EMAIL_CLAIM.
+   */
+  getIdToken: () => Promise<string>;
   /**
    * POSTs the listing as a JSON body to `/v1/listings` and returns the parsed
    * { status, body }. `tarball` is the BASE64-encoded gzip pack bytes — the
@@ -396,6 +428,7 @@ export interface PublishResult {
 export async function runPublish(
   targetPath: string,
   deps: PublishDeps,
+  opts: { publishAsHandle?: string } = {},
 ): Promise<PublishResult> {
   // 1. Logged-in gate — refuse BEFORE any packing/upload.
   const idToken = deps.loadIdToken();
@@ -403,6 +436,10 @@ export async function runPublish(
     throw new Error('Not logged in — run `hq login` before publishing. Nothing was uploaded.');
   }
   const author = resolveAuthor(peekIdToken(idToken));
+  const publishAsHandle =
+    typeof opts.publishAsHandle === 'string' && opts.publishAsHandle.length > 0
+      ? opts.publishAsHandle
+      : undefined;
 
   // Resolve a payload dir. We stamp/validate against a temp copy so we never
   // mutate the user's working tree's package.yaml.
@@ -420,7 +457,14 @@ export async function runPublish(
     if (!fs.existsSync(path.join(payloadDir, 'package.yaml'))) {
       throw new Error(`package.yaml missing from ${absTarget} — nothing was uploaded.`);
     }
-    stampAuthorIntoPackage(payloadDir, author);
+    // On the on-behalf path (`--as <handle>`) the SERVER is authoritative for
+    // attribution (it resolves the target creator by handle and ignores the
+    // manifest/stamped author), so we must NOT overwrite the manifest's author
+    // with the CALLER's identity — the manifest already names the target
+    // creator. Stamp the caller only on the normal self-publish path.
+    if (!publishAsHandle) {
+      stampAuthorIntoPackage(payloadDir, author);
+    }
 
     // 3. Validate with the canonical 10-rule validator. Throws on any failure;
     //    we have uploaded nothing at this point.
@@ -430,7 +474,13 @@ export async function runPublish(
     //    JSON.parses the body, so we send the gzip tarball base64-encoded
     //    inside a JSON listing request (NOT a raw octet-stream body).
     const tarballBytes = tarballPayload(payloadDir);
-    const token = await deps.getAccessToken();
+    // On-behalf publishes are staff-gated server-side and the staff gate reads
+    // the id_token `email` claim — send the ID token, not the access token
+    // (which has no email and would 403 NO_EMAIL_CLAIM). Normal self-publish
+    // continues to use the access token.
+    const token = publishAsHandle
+      ? await deps.getIdToken()
+      : await deps.getAccessToken();
     const listing: ListingRequest = {
       type: inferListingType(pkg),
       name: pkg.name,
@@ -438,9 +488,12 @@ export async function runPublish(
       version: pkg.version,
       summary: pkg.description,
       contributes: summarizeContributes(pkg.contributes) || undefined,
-      // Server prefers the caller's claimed creator handle, but we stamp our
-      // resolved handle as a backwards-compat fallback.
-      creatorHandle: author.handle,
+      // On-behalf: send the target handle so the body is self-describing (the
+      // server is authoritative for attribution either way). Normal: our
+      // resolved handle is a backwards-compat fallback under the server's
+      // claimed-handle lookup.
+      creatorHandle: publishAsHandle ?? author.handle,
+      ...(publishAsHandle ? { publishAsHandle } : {}),
       tarball: Buffer.from(tarballBytes).toString('base64'),
     };
     const { status, body } = await deps.upload({ token, listing });
@@ -468,8 +521,15 @@ export function registerPublishCommand(program: Command): void {
     .description(
       'Package a skill/worker pack and submit it to the HQ marketplace (POST /v1/listings).',
     )
-    .action(async (targetPath: string) => {
+    .option(
+      '--as <handle>',
+      'Publish on behalf of a seeded, unclaimed creator by handle (HQ staff only). ' +
+        'The listing is attributed to that creator instead of you.',
+    )
+    .option('--on-behalf <handle>', 'Alias for --as.')
+    .action(async (targetPath: string, options: { as?: string; onBehalf?: string }) => {
       try {
+        const publishAsHandle = options.as ?? options.onBehalf;
         const hqRoot = findHqRoot();
         const result = await runPublish(targetPath, {
           loadIdToken: () => {
@@ -478,6 +538,7 @@ export function registerPublishCommand(program: Command): void {
             return cached.idToken;
           },
           getAccessToken: () => ensureCognitoToken({ interactive: false }),
+          getIdToken: () => ensureCognitoIdToken({ interactive: false }),
           upload: async ({ token, listing }) => {
             // JSON body (application/json) — the deployed handler JSON.parses
             // the body and base64-decodes `listing.tarball`. vaultApiFetch
@@ -493,7 +554,7 @@ export function registerPublishCommand(program: Command): void {
           },
           hqRoot,
           hqVersion: readHqVersion(hqRoot),
-        });
+        }, { publishAsHandle });
         console.log(chalk.green(result.notice));
         // Only print the locally-resolved author as a fallback when the server
         // did NOT return its own resolved handle (already in the notice).

package/src/utils/cognito-session.ts

@@ -318,6 +318,62 @@ export async function ensureCognitoToken(options: {
   return tokens.accessToken;
 }
 
+/**
+ * Return a non-expired Cognito **ID** token (mirrors `ensureCognitoToken`'s
+ * refresh/login flow but yields the id_token, not the access token).
+ *
+ * Staff-gated vault-API routes (`assertStaffCaller`) read the `email` claim,
+ * which Cognito puts on the ID token ONLY — the access token has no `email`, so
+ * sending it returns `403 NO_EMAIL_CLAIM`. Callers performing a staff action
+ * (e.g. `hq publish --as <handle>`) MUST send the ID token. For machine
+ * identities the vault API already authenticates with the ID token, so this is
+ * identical to `ensureCognitoToken` there.
+ */
+export async function ensureCognitoIdToken(options: {
+  interactive?: boolean;
+} = {}): Promise<string> {
+  const interactive = options.interactive ?? true;
+
+  if (isMachineIdentity()) {
+    const machine = await getValidMachineTokens(DEFAULT_COGNITO);
+    return machine.idToken;
+  }
+
+  const cached = loadCachedTokens();
+
+  if (cached && !isExpiring(cached, 120)) {
+    return cached.idToken;
+  }
+
+  if (cached) {
+    try {
+      if (interactive) {
+        console.error(chalk.dim("  Refreshing expiring HQ session..."));
+      }
+      const refreshed = await refreshTokens(DEFAULT_COGNITO, cached.refreshToken);
+      return refreshed.idToken;
+    } catch (err) {
+      if (interactive) {
+        console.error(
+          chalk.dim(
+            `  Refresh failed (${err instanceof Error ? err.message : err}), falling back to browser login`,
+          ),
+        );
+      }
+    }
+  }
+
+  if (!interactive) {
+    throw new Error(
+      "No valid HQ session and interactive login is disabled. Run `hq login` first.",
+    );
+  }
+
+  console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
+  const tokens = await browserLogin(DEFAULT_COGNITO);
+  return tokens.idToken;
+}
+
 /**
  * The CLI's own ClientInfo. Resolved once at module load so every VaultClient
  * built in this process stamps the same name/version onto its requests.