@kruvisolutions/sf-access

An sf plugin that opens customer Salesforce orgs with a short-lived session Kruvi Access mints, records and can revoke. Engineers never hold a password, a private key or a consumer secret.

sf plugins install @kruvisolutions/sf-access

sf access login --instance https://tokenry.kruvi.co.uk
sf access orgs
sf access open acme --ticket ISM-4412 --reason "Reproduce shift rollover bug"
sf data query --target-org kruvi-acme-production --query "select Id from Account limit 1"
sf access logout

On first install sf will say this plugin is not digitally signed and ask you to confirm. That is expected: Salesforce only signs its own plugins, and every third-party one is treated the same way. The published package contains the compiled sources and nothing else — read them before you agree if you would rather see for yourself.

What each command does

| Command | What happens | |---|---| | sf access login | Device-code flow. Prints a short code, you approve it in a browser that already has your second factor, and this terminal gets a session. Nothing is minted. | | sf access orgs | The customer orgs you hold a grant on right now, and the Salesforce identity each grant names. | | sf access open <org> | Mints a session and logs sf in under an alias. --as picks the Salesforce identity where you hold more than one; --browser opens a single-use frontdoor URL instead. | | sf access status | What this terminal is holding: which orgs, under which alias, as whom, and how long each has left. | | sf access refresh | Renews what has run out, in one command. Rarely needed - see below. | | sf access logout | Revokes the session at the server, logs sf out of every org this plugin opened, and clears the keychain. |

open takes an org's name, a unique part of it, or its id. An ambiguous name is refused with the candidates listed rather than guessed at — opening the wrong customer's org is the worst thing this plugin could do.

One org can carry more than one Salesforce identity — a shared support login and your own named user, say — and the org name alone cannot tell them apart. Name the one you want with --as:

sf access open acme --as support --ticket ISM-4412 --reason "Check the rollover flow"

The identity also goes into the default alias in that case, so opening as two people gives you two aliases rather than one that silently changes hands. sf access orgs lists the identity for each grant.

Where the session is kept

The refresh token goes to whatever the operating system provides:

| Platform | Store | |---|---| | macOS | the login keychain, via security | | Linux | the Secret Service, via secret-tool | | Windows | DPAPI under your user account, via PowerShell | | anything else | a 0600 file, with a warning every time you log in |

No native module, so sf plugins install needs no compiler and cannot fail for want of a prebuild. The fallback exists because headless CI and bare containers have no keychain, and refusing to work there would be worse than saying plainly what we are doing.

KRUVI_CONFIG_HOME moves everything this plugin writes, which is what CI and the tests use.

Sessions renew themselves

A session this plugin mints is short, because re-minting through the broker is silent and free. That only helps if something remembers to do it, and nobody is going to run a refresh command every two hours.

So the renewal happens where the need appears. The plugin registers an oclif prerun hook, which runs before every sf command:

sf data query --target-org kruvi-acme --query "select Id from Account limit 1"
# session had expired; it is renewed and the query runs

This is the ergonomics of a permanent credential without one existing. The only long-lived secret is the refresh token in your keychain, which is revocable in one place, and every renewal is a real mint that the customer audit trail records.

What it will not do:

• Slow down commands that have nothing to do with us. One small file read decides that, and nothing touches the network or the keychain until a renewal is certain.
• Break a command it has no business in. Any failure warns and gets out of the way.
• Invent a ticket or a reason. Where a customer requires them, the platform decides whether the one you gave earlier still covers this session. That window is the customer setting, not ours to widen.
• Change who you are. The org and identity come from what was opened before, never resolved afresh.

It renews the org named by --target-org/-o, or by your configured default target org. Set KRUVI_NO_AUTO_RENEW=1 to turn it off.

What never happens

• A Salesforce token never appears in an argument. It reaches sf through SF_ACCESS_TOKEN, so it is not in the process list and not in your shell history.
• An alias never reaches a shell unchecked. On Windows the sf shim needs shell: true, so aliases are validated against a strict pattern first.
• Logging out is not just forgetting. The refresh token is revoked at the server (RFC 7009) before anything local is cleared, and if that call fails you are told rather than reassured.

Working on it

npm install
npm run typecheck
npm test          # no network, no keychain, no home directory
npm run build

sf plugins link .   # run the local build as a real sf plugin
sf plugins unlink . # when you are done

KRUVI_ACCESS_URL sets the deployment without --instance, which is the easiest way to point a shell at a staging instance.

Licence

MIT. The plugin is a client: it does nothing without a Kruvi Access deployment behind it, and it is the part that runs on your own machines, touches your keychain and hooks your sf commands. Being able to read exactly what it does is the point.