Skip to content

fix(credential): explain non-exportable credentials during local injection - #34

Open
Goldokpa wants to merge 3 commits into
mainfrom
fix/non-exportable-credentials
Open

Goldokpa wants to merge 3 commits into
mainfrom
fix/non-exportable-credentials

Conversation

@Goldokpa

Copy link
Copy Markdown
Contributor

What changed

IdentArk now treats brokered credentials as non-exportable by default. Local injection (identark credential inject, agent run, agent dev) therefore works only when both of these hold:

  • you are signed in with device login (identark auth login), or you use a developer API key granted credentials:resolve explicitly. No key preset and no org:admin key includes it, and agent-bound keys can never hold it;
  • an org owner has marked the credential exportable.

Before this PR, a refusal was swallowed by a generic except Exception and the user saw only "Could not resolve required credential X". Now:

  • Typed error. A 403 from /v1/credentials/resolve raises CredentialExportDeniedError, carrying a message, an explanation and a next step for the specific reason:
    • credential_not_exportable: "Credential prod/openai is not exportable", and an org owner can allow local export, or a managed connector can be used instead;
    • insufficient_scope: the key lacks credentials:resolve, which org:admin and presets don't include; next step identark auth login;
    • agent_key_cannot_export: the key is bound to an agent;
    • any other 403: generic guidance covering both conditions.
  • Caught where it matters. All three call sites catch it before the generic handler. A required credential stops the run (exit 1, child not started) with the reason. An optional one warns and continues without it.
  • Env-key hint. When an API key in IDENTARK_API_KEY / IDENTARK_SESSION_TOKEN / IDENTARK_TOKEN shadows device login, the next step names it: unset IDENTARK_API_KEY && identark auth login. The key value is never printed.
  • Docs. The README's isolation-boundary section documents the two conditions, and CHANGELOG has an entry under Unreleased.

Why

The control-plane change (identArk/backend#47) makes plaintext export opt-in. Without this PR, every user whose key or credential no longer qualifies would see an unexplained failure.

Closes # (none)

Verification

uv sync --locked --extra dev
uv run --locked ruff format --check identark_cli tests
uv run --locked ruff check identark_cli tests
uv run --locked mypy identark_cli
uv run --locked pytest            # 142 passed (7 new in tests/test_credential_export.py)
uv build && uv run --locked python scripts/check_distribution.py dist/*   # boundary verified

Checklist

  • I added or updated tests for changed behaviour.
  • I ran the relevant format, lint, type, and test commands locally.
  • I updated public documentation and the changelog when appropriate.
  • I preserved backward compatibility or documented an approved migration. The command surface is unchanged; the README documents the new server-side requirement.
  • I included no secret, token, customer data, signed URL, or private service
    implementation detail.
  • I did not make the CLI authorise, approve, or audit an operation that the
    hosted service must decide. The CLI only explains the server's 403.
  • Security-sensitive failures deny access rather than silently allowing it.
  • My commits are signed off under the Developer Certificate of Origin.

Security notes

  • Credential flow: unchanged; the CLI still calls /v1/credentials/resolve, and the server decides.
  • Exit behaviour: on a 403 the CLI never starts the child process for a required credential.
  • No sensitive output: messages contain the credential path and the env-var name, never a token or a value.

…ction

IdentArk credentials are non-exportable by default. Local injection
(`credential inject`, `agent run`, `agent dev`) now needs device login or a
developer key granted `credentials:resolve` explicitly, plus a credential an
org owner marked exportable.

A 403 from /v1/credentials/resolve is now raised as
CredentialExportDeniedError with guidance for the specific reason (not
exportable, missing scope, agent-bound key) and caught before the generic
handler, so the user sees why the child process was not started. When an
API key in the environment shadows device login, the next step says which
variable to unset.

README documents the two conditions.

Signed-off-by: Gold okpa <okpagold@gmail.com>
Signed-off-by: Gold okpa <okpagold@gmail.com>
…e guidance

Signed-off-by: Gold okpa <okpagold@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant