Dogcows Code - chaz/p5-File-KDBX/blob - lib/File/KDBX/Object.pm

   1 package File::KDBX::Object;
   2 # ABSTRACT: A KDBX database object
   3
   4 use warnings;
   5 use strict;
   6
   7 use Devel::GlobalDestruction;
   8 use File::KDBX::Constants qw(:bool);
   9 use File::KDBX::Error;
  10 use File::KDBX::Util qw(:uuid);
  11 use Hash::Util::FieldHash qw(fieldhashes);
  12 use List::Util qw(any first);
  13 use Ref::Util qw(is_arrayref is_plain_arrayref is_plain_hashref is_ref);
  14 use Scalar::Util qw(blessed weaken);
  15 use namespace::clean;
  16
  17 our $VERSION = '999.999'; # VERSION
  18
  19 fieldhashes \my (%KDBX, %PARENT, %TXNS, %REFS, %SIGNALS);
  20
  21 =method new
  22
  23     $object = File::KDBX::Object->new;
  24     $object = File::KDBX::Object->new(%attributes);
  25     $object = File::KDBX::Object->new(\%data);
  26     $object = File::KDBX::Object->new(\%data, $kdbx);
  27
  28 Construct a new KDBX object.
  29
  30 There is a subtlety to take note of. There is a significant difference between:
  31
  32     File::KDBX::Entry->new(username => 'iambatman');
  33
  34 and:
  35
  36     File::KDBX::Entry->new({username => 'iambatman'}); # WRONG
  37
  38 In the first, an empty object is first created and then initialized with whatever I<attributes> are given. In
  39 the second, a hashref is blessed and essentially becomes the object. The significance is that the hashref
  40 key-value pairs will remain as-is so the structure is expected to adhere to the shape of a raw B<Object>
  41 (which varies based on the type of object), whereas with the first the attributes will set the structure in
  42 the correct way (just like using the object accessors / getters / setters).
  43
  44 The second example isn't I<generally> wrong -- this type of construction is supported for a reason, to allow
  45 for working with KDBX objects at a low level -- but it is wrong in this specific case only because
  46 C<< {username => $str} >> isn't a valid raw KDBX entry object. The L</username> attribute is really a proxy
  47 for the C<UserName> string, so the equivalent raw entry object should be
  48 C<< {strings => {UserName => {value => $str}}} >>. These are roughly equivalent:
  49
  50     File::KDBX::Entry->new(username => 'iambatman');
  51     File::KDBX::Entry->new({strings => {UserName => {value => 'iambatman'}}});
  52
  53 If this explanation went over your head, that's fine. Just stick with the attributes since they are typically
  54 easier to use correctly and provide the most convenience. If in the future you think of some kind of KDBX
  55 object manipulation you want to do that isn't supported by the accessors and methods, just know you I<can>
  56 access an object's data directly.
  57
  58 =cut
  59
  60 sub new {
  61     my $class = shift;
  62
  63     # copy constructor
  64     return $_[0]->clone if @_ == 1 && blessed $_[0] && $_[0]->isa($class);
  65
  66     my $data;
  67     $data = shift if is_plain_hashref($_[0]);
  68
  69     my $kdbx;
  70     $kdbx = shift if @_ % 2 == 1;
  71
  72     my %args = @_;
  73     $args{kdbx} //= $kdbx if defined $kdbx;
  74
  75     my $self = bless $data // {}, $class;
  76     $self->init(%args);
  77     $self->_set_nonlazy_attributes if !$data;
  78     return $self;
  79 }
  80
  81 sub _set_nonlazy_attributes { die 'Not implemented' }
  82
  83 =method init
  84
  85     $object = $object->init(%attributes);
  86
  87 Called by the constructor to set attributes. You normally should not call this.
  88
  89 =cut
  90
  91 sub init {
  92     my $self = shift;
  93     my %args = @_;
  94
  95     while (my ($key, $val) = each %args) {
  96         if (my $method = $self->can($key)) {
  97             $self->$method($val);
  98         }
  99     }
 100
 101     return $self;
 102 }
 103
 104 =method wrap
 105
 106     $object = File::KDBX::Object->wrap($object);
 107
 108 Ensure that a KDBX object is blessed.
 109
 110 =cut
 111
 112 sub wrap {
 113     my $class   = shift;
 114     my $object  = shift;
 115     return $object if blessed $object && $object->isa($class);
 116     return $class->new(@_, @$object) if is_arrayref($object);
 117     return $class->new($object, @_);
 118 }
 119
 120 =method label
 121
 122     $label = $object->label;
 123     $object->label($label);
 124
 125 Get or set the object's label, a text string that can act as a non-unique identifier. For an entry, the label
 126 is its title string. For a group, the label is its name.
 127
 128 =cut
 129
 130 sub label { die 'Not implemented' }
 131
 132 =method clone
 133
 134     $object_copy = $object->clone(%options);
 135     $object_copy = File::KDBX::Object->new($object);
 136
 137 Make a clone of an object. By default the clone is indeed an exact copy that is connected to the same database
 138 but not actually included in the object tree (i.e. it has no parent group). Some options are allowed to get
 139 different effects:
 140
 141 =for :list
 142 * C<new_uuid> - If set, generate a new UUID for the copy (default: false)
 143 * C<parent> - If set, add the copy to the same parent group, if any (default: false)
 144 * C<relabel> - If set, append " - Copy" to the object's title or name (default: false)
 145 * C<entries> - If set, copy child entries, if any (default: true)
 146 * C<groups> - If set, copy child groups, if any (default: true)
 147 * C<history> - If set, copy entry history, if any (default: true)
 148 * C<reference_password> - Toggle whether or not cloned entry's Password string should be set as a field
 149     reference to the original entry's Password string (default: false)
 150 * C<reference_username> - Toggle whether or not cloned entry's UserName string should be set as a field
 151     reference to the original entry's UserName string (default: false)
 152
 153 =cut
 154
 155 my %CLONE = (entries => 1, groups => 1, history => 1);
 156 sub clone {
 157     my $self = shift;
 158     my %args = @_;
 159
 160     local $CLONE{new_uuid}              = $args{new_uuid} // $args{parent} // 0;
 161     local $CLONE{entries}               = $args{entries}  // 1;
 162     local $CLONE{groups}                = $args{groups}   // 1;
 163     local $CLONE{history}               = $args{history}  // 1;
 164     local $CLONE{reference_password}    = $args{reference_password} // 0;
 165     local $CLONE{reference_username}    = $args{reference_username} // 0;
 166
 167     require Storable;
 168     my $copy = Storable::dclone($self);
 169
 170     if ($args{relabel} and my $label = $self->label) {
 171         $copy->label("$label - Copy");
 172     }
 173     if ($args{parent} and my $parent = $self->group) {
 174         $parent->add_object($copy);
 175     }
 176
 177     return $copy;
 178 }
 179
 180 sub STORABLE_freeze {
 181     my $self    = shift;
 182     my $cloning = shift;
 183
 184     my $copy = {%$self};
 185     delete $copy->{entries} if !$CLONE{entries};
 186     delete $copy->{groups}  if !$CLONE{groups};
 187     delete $copy->{history} if !$CLONE{history};
 188
 189     return ($cloning ? Hash::Util::FieldHash::id($self) : ''), $copy;
 190 }
 191
 192 sub STORABLE_thaw {
 193     my $self    = shift;
 194     my $cloning = shift;
 195     my $addr    = shift;
 196     my $copy    = shift;
 197
 198     @$self{keys %$copy} = values %$copy;
 199
 200     if ($cloning) {
 201         my $kdbx = $KDBX{$addr};
 202         $self->kdbx($kdbx) if $kdbx;
 203     }
 204
 205     if (defined $self->{uuid}) {
 206         if (($CLONE{reference_password} || $CLONE{reference_username}) && $self->can('strings')) {
 207             my $uuid = format_uuid($self->{uuid});
 208             my $clone_obj = do {
 209                 local $CLONE{new_uuid}              = 0;
 210                 local $CLONE{entries}               = 1;
 211                 local $CLONE{groups}                = 1;
 212                 local $CLONE{history}               = 1;
 213                 local $CLONE{reference_password}    = 0;
 214                 local $CLONE{reference_username}    = 0;
 215                 # Clone only the entry's data and manually bless to avoid infinite recursion.
 216                 bless Storable::dclone({%$copy}), 'File::KDBX::Entry';
 217             };
 218             my $txn = $self->begin_work(snapshot => $clone_obj);
 219             if ($CLONE{reference_password}) {
 220                 $self->password("{REF:P\@I:$uuid}");
 221             }
 222             if ($CLONE{reference_username}) {
 223                 $self->username("{REF:U\@I:$uuid}");
 224             }
 225             $txn->commit;
 226         }
 227         $self->uuid(generate_uuid) if $CLONE{new_uuid};
 228     }
 229
 230     # Dualvars aren't cloned as dualvars, so dualify the icon.
 231     $self->icon_id($self->{icon_id}) if defined $self->{icon_id};
 232 }
 233
 234 =attr kdbx
 235
 236     $kdbx = $object->kdbx;
 237     $object->kdbx($kdbx);
 238
 239 Get or set the L<File::KDBX> instance connected with this object. Throws if the object is disconnected. Other
 240 object methods might only work if the object is connected to a database and so they might also throw if the
 241 object is disconnected. If you're not sure if an object is connected, try L</is_connected>.
 242
 243 =cut
 244
 245 sub kdbx {
 246     my $self = shift;
 247     $self = $self->new if !ref $self;
 248     if (@_) {
 249         if (my $kdbx = shift) {
 250             $KDBX{$self} = $kdbx;
 251             weaken $KDBX{$self};
 252         }
 253         else {
 254             delete $KDBX{$self};
 255         }
 256     }
 257     $KDBX{$self} or throw 'Object is disconnected', object => $self;
 258 }
 259
 260 =method is_connected
 261
 262     $bool = $object->is_connected;
 263
 264 Determine whether or not an object is connected to a database.
 265
 266 =cut
 267
 268 sub is_connected {
 269     my $self = shift;
 270     return !!eval { $self->kdbx };
 271 }
 272
 273 =method id
 274
 275     $string_uuid = $object->id;
 276     $string_uuid = $object->id($delimiter);
 277
 278 Get the unique identifier for this object as a B<formatted> UUID string, typically for display purposes. You
 279 could use this to compare with other identifiers formatted with the same delimiter, but it is more efficient
 280 to use the raw UUID for that purpose (see L</uuid>).
 281
 282 A delimiter can optionally be provided to break up the UUID string visually. See
 283 L<File::KDBX::Util/format_uuid>.
 284
 285 =cut
 286
 287 sub id { format_uuid(shift->uuid, @_) }
 288
 289 =method group
 290
 291     $parent_group = $object->group;
 292     $object->group($parent_group);
 293
 294 Get or set the parent group to which an object belongs or C<undef> if it belongs to no group.
 295
 296 =cut
 297
 298 sub group {
 299     my $self = shift;
 300
 301     if (my $new_group = shift) {
 302         my $old_group = $self->group;
 303         return $new_group if Hash::Util::FieldHash::id($old_group) == Hash::Util::FieldHash::id($new_group);
 304         # move to a new parent
 305         $self->remove(signal => 0) if $old_group;
 306         $self->location_changed('now');
 307         $new_group->add_object($self);
 308     }
 309
 310     my $id   = Hash::Util::FieldHash::id($self);
 311     if (my $group = $PARENT{$self}) {
 312         my $method = $self->_parent_container;
 313         return $group if first { $id == Hash::Util::FieldHash::id($_) } @{$group->$method};
 314         delete $PARENT{$self};
 315     }
 316     # always get lineage from root to leaf because the other way requires parent, so it would be recursive
 317     my $lineage = $self->kdbx->_trace_lineage($self) or return;
 318     my $group = pop @$lineage or return;
 319     $PARENT{$self} = $group; weaken $PARENT{$self};
 320     return $group;
 321 }
 322
 323 sub _set_group {
 324     my $self = shift;
 325     if (my $parent = shift) {
 326         $PARENT{$self} = $parent;
 327         weaken $PARENT{$self};
 328     }
 329     else {
 330         delete $PARENT{$self};
 331     }
 332     return $self;
 333 }
 334
 335 ### Name of the parent attribute expected to contain the object
 336 sub _parent_container { die 'Not implemented' }
 337
 338 =method lineage
 339
 340     \@lineage = $object->lineage;
 341     \@lineage = $object->lineage($base_group);
 342
 343 Get the direct line of ancestors from C<$base_group> (default: the root group) to an object. The lineage
 344 includes the base group but I<not> the target object. Returns C<undef> if the target is not in the database
 345 structure. Returns an empty arrayref is the object itself is a root group.
 346
 347 =cut
 348
 349 sub lineage {
 350     my $self = shift;
 351     my $base = shift;
 352
 353     my $base_addr = $base ? Hash::Util::FieldHash::id($base) : 0;
 354
 355     # try leaf to root
 356     my @path;
 357     my $object = $self;
 358     while ($object = $object->group) {
 359         unshift @path, $object;
 360         last if $base_addr == Hash::Util::FieldHash::id($object);
 361     }
 362     return \@path if @path && ($base_addr == Hash::Util::FieldHash::id($path[0]) || $path[0]->is_root);
 363
 364     # try root to leaf
 365     return $self->kdbx->_trace_lineage($self, $base);
 366 }
 367
 368 =method remove
 369
 370     $object = $object->remove(%options);
 371
 372 Remove an object from its parent. If the object is a group, all contained objects stay with the object and so
 373 are removed as well, just like cutting off a branch takes the leafs as well. Options:
 374
 375 =for :list
 376 * C<signal> Whether or not to signal the removal to the connected database (default: true)
 377
 378 =cut
 379
 380 sub remove {
 381     my $self = shift;
 382     my $parent = $self->group;
 383     $parent->remove_object($self, @_) if $parent;
 384     $self->_set_group(undef);
 385     return $self;
 386 }
 387
 388 =method recycle
 389
 390     $object = $object->recycle;
 391
 392 Remove an object from its parent and add it to the connected database's recycle bin group.
 393
 394 =cut
 395
 396 sub recycle {
 397     my $self = shift;
 398     return $self->group($self->kdbx->recycle_bin);
 399 }
 400
 401 =method recycle_or_remove
 402
 403     $object = $object->recycle_or_remove;
 404
 405 Recycle or remove an object, depending on the connected database's L<File::KDBX/recycle_bin_enabled>. If the
 406 object is not connected to a database or is already in the recycle bin, remove it.
 407
 408 =cut
 409
 410 sub recycle_or_remove {
 411     my $self = shift;
 412     my $kdbx = eval { $self->kdbx };
 413     if ($kdbx && $kdbx->recycle_bin_enabled && !$self->is_recycled) {
 414         $self->recycle;
 415     }
 416     else {
 417         $self->remove;
 418     }
 419 }
 420
 421 =method is_recycled
 422
 423     $bool = $object->is_recycled;
 424
 425 Get whether or not an object is in a recycle bin.
 426
 427 =cut
 428
 429 sub is_recycled {
 430     my $self = shift;
 431     eval { $self->kdbx } or return FALSE;
 432     return !!($self->group && any { $_->is_recycle_bin } @{$self->lineage});
 433 }
 434
 435 ##############################################################################
 436
 437 =method tag_list
 438
 439     @tags = $entry->tag_list;
 440
 441 Get a list of tags, split from L</tag> using delimiters C<,>, C<.>, C<:>, C<;> and whitespace.
 442
 443 =cut
 444
 445 sub tag_list {
 446     my $self = shift;
 447     return grep { $_ ne '' } split(/[,\.:;]|\s+/, trim($self->tags) // '');
 448 }
 449
 450 =method custom_icon
 451
 452     $image_data = $object->custom_icon;
 453     $image_data = $object->custom_icon($image_data, %attributes);
 454
 455 Get or set an icon image. Returns C<undef> if there is no custom icon set. Setting a custom icon will change
 456 the L</custom_icon_uuid> attribute.
 457
 458 Custom icon attributes (supported in KDBX4.1 and greater):
 459
 460 =for :list
 461 * C<name> - Name of the icon (text)
 462 * C<last_modification_time> - Just what it says (datetime)
 463
 464 =cut
 465
 466 sub custom_icon {
 467     my $self = shift;
 468     my $kdbx = $self->kdbx;
 469     if (@_) {
 470         my $img = shift;
 471         my $uuid = defined $img ? $kdbx->add_custom_icon($img, @_) : undef;
 472         $self->icon_id(0) if $uuid;
 473         $self->custom_icon_uuid($uuid);
 474         return $img;
 475     }
 476     return $kdbx->custom_icon_data($self->custom_icon_uuid);
 477 }
 478
 479 =method custom_data
 480
 481     \%all_data = $object->custom_data;
 482     $object->custom_data(\%all_data);
 483
 484     \%data = $object->custom_data($key);
 485     $object->custom_data($key => \%data);
 486     $object->custom_data(%data);
 487     $object->custom_data(key => $value, %data);
 488
 489 Get and set custom data. Custom data is metadata associated with an object. It is a set of key-value pairs
 490 used to store arbitrary data, usually used by software like plug-ins to keep track of state rather than by end
 491 users.
 492
 493 Each data item can have a few attributes associated with it.
 494
 495 =for :list
 496 * C<key> - A unique text string identifier used to look up the data item (required)
 497 * C<value> - A text string value (required)
 498 * C<last_modification_time> (optional, KDBX4.1+)
 499
 500 =cut
 501
 502 sub custom_data {
 503     my $self = shift;
 504     $self->{custom_data} = shift if @_ == 1 && is_plain_hashref($_[0]);
 505     return $self->{custom_data} //= {} if !@_;
 506
 507     my %args = @_     == 2 ? (key => shift, value => shift)
 508              : @_ % 2 == 1 ? (key => shift, @_) : @_;
 509
 510     if (!$args{key} && !$args{value}) {
 511         my %standard = (key => 1, value => 1, last_modification_time => 1);
 512         my @other_keys = grep { !$standard{$_} } keys %args;
 513         if (@other_keys == 1) {
 514             my $key = $args{key} = $other_keys[0];
 515             $args{value} = delete $args{$key};
 516         }
 517     }
 518
 519     my $key = $args{key} or throw 'Must provide a custom_data key to access';
 520
 521     return $self->{custom_data}{$key} = $args{value} if is_plain_hashref($args{value});
 522
 523     while (my ($field, $value) = each %args) {
 524         $self->{custom_data}{$key}{$field} = $value;
 525     }
 526     return $self->{custom_data}{$key};
 527 }
 528
 529 =method custom_data_value
 530
 531     $value = $object->custom_data_value($key);
 532
 533 Exactly the same as L</custom_data> except returns just the custom data's value rather than a structure of
 534 attributes. This is a shortcut for:
 535
 536     my $data = $object->custom_data($key);
 537     my $value = defined $data ? $data->{value} : undef;
 538
 539 =cut
 540
 541 sub custom_data_value {
 542     my $self = shift;
 543     my $data = $self->custom_data(@_) // return undef;
 544     return $data->{value};
 545 }
 546
 547 ##############################################################################
 548
 549 =method begin_work
 550
 551     $txn = $object->begin_work(%options);
 552     $object->begin_work(%options);
 553
 554 Begin a new transaction. Returns a L<File::KDBX::Transaction> object that can be scoped to ensure a rollback
 555 occurs if exceptions are thrown. Alternatively, if called in void context, there will be no
 556 B<File::KDBX::Transaction> and it is instead your responsibility to call L</commit> or L</rollback> as
 557 appropriate. It is undefined behavior to call these if a B<File::KDBX::Transaction> exists. Recursive
 558 transactions are allowed.
 559
 560 Signals created during a transaction are delayed until all transactions are resolved. If the outermost
 561 transaction is committed, then the signals are de-duplicated and delivered. Otherwise the signals are dropped.
 562 This means that the KDBX database will not fix broken references or mark itself dirty until after the
 563 transaction is committed.
 564
 565 How it works: With the beginning of a transaction, a snapshot of the object is created. In the event of
 566 a rollback, the object's data is replaced with data from the snapshot.
 567
 568 By default, the snapshot is shallow (i.e. does not include subroups, entries or historical entries). This
 569 means that only modifications to the object itself (its data, fields, strings, etc.) are atomic; modifications
 570 to subroups etc., including adding or removing items, are auto-committed instantly and will persist regardless
 571 of the result of the pending transaction. You can override this for groups, entries and history independently
 572 using options:
 573
 574 =for :list
 575 * C<entries> - If set, snapshot entries within a group, deeply (default: false)
 576 * C<groups> - If set, snapshot subroups within a group, deeply (default: false)
 577 * C<history> - If set, snapshot historical entries within an entry (default: false)
 578
 579 For example, if you begin a transaction on a group object using the C<entries> option, like this:
 580
 581     $group->begin_work(entries => 1);
 582
 583 Then if you modify any of the group's entries OR add new entries OR delete entries, all of that will be undone
 584 if the transaction is rolled back. With a default-configured transaction, however, changes to entries are kept
 585 even if the transaction is rolled back.
 586
 587 =cut
 588
 589 sub begin_work {
 590     my $self = shift;
 591
 592     if (defined wantarray) {
 593         require File::KDBX::Transaction;
 594         return File::KDBX::Transaction->new($self, @_);
 595     }
 596
 597     my %args = @_;
 598     my $orig = $args{snapshot} // do {
 599         my $c = $self->clone(
 600             entries => $args{entries} // 0,
 601             groups  => $args{groups}  // 0,
 602             history => $args{history} // 0,
 603         );
 604         $c->{entries} = $self->{entries} if !$args{entries};
 605         $c->{groups}  = $self->{groups}  if !$args{groups};
 606         $c->{history} = $self->{history} if !$args{history};
 607         $c;
 608     };
 609
 610     my $id = Hash::Util::FieldHash::id($orig);
 611     _save_references($id, $self, $orig);
 612
 613     $self->_signal_begin_work;
 614
 615     push @{$self->_txns}, $orig;
 616 }
 617
 618 =method commit
 619
 620     $object->commit;
 621
 622 Commit a transaction, making updates to C<$object> permanent. Returns itself to allow method chaining.
 623
 624 =cut
 625
 626 sub commit {
 627     my $self = shift;
 628     my $orig = pop @{$self->_txns} or return $self;
 629     $self->_commit($orig);
 630     my $signals = $self->_signal_commit;
 631     $self->_signal_send($signals) if !$self->_in_txn;
 632     return $self;
 633 }
 634
 635 =method rollback
 636
 637     $object->rollback;
 638
 639 Roll back the most recent transaction, throwing away any updates to the L</object> made since the transaction
 640 began. Returns itself to allow method chaining.
 641
 642 =cut
 643
 644 sub rollback {
 645     my $self = shift;
 646
 647     my $orig = pop @{$self->_txns} or return $self;
 648
 649     my $id = Hash::Util::FieldHash::id($orig);
 650     _restore_references($id, $orig);
 651
 652     $self->_signal_rollback;
 653
 654     return $self;
 655 }
 656
 657 # Get whether or not there is at least one pending transaction.
 658 sub _in_txn { scalar @{$_[0]->_txns} }
 659
 660 # Get an array ref of pending transactions.
 661 sub _txns   { $TXNS{$_[0]} //= [] }
 662
 663 # The _commit hook notifies subclasses that a commit has occurred.
 664 sub _commit { die 'Not implemented' }
 665
 666 # Get a reference to an object that represents an object's committed state. If there is no pending
 667 # transaction, this is just $self. If there is a transaction, this is the snapshot take before the transaction
 668 # began. This method is private because it provides direct access to the actual snapshot. It is important that
 669 # the snapshot not be changed or a rollback would roll back to an altered state.
 670 # This is used by File::KDBX::Dumper::XML so as to not dump uncommitted changes.
 671 sub _committed {
 672     my $self = shift;
 673     my ($orig) = @{$self->_txns};
 674     return $orig // $self;
 675 }
 676
 677 # In addition to cloning an object when beginning work, we also keep track its hashrefs and arrayrefs
 678 # internally so that we can restore to the very same structures in the case of a rollback.
 679 sub _save_references {
 680     my $id   = shift;
 681     my $self = shift;
 682     my $orig = shift;
 683
 684     if (is_plain_arrayref($orig)) {
 685         for (my $i = 0; $i < @$orig; ++$i) {
 686             _save_references($id, $self->[$i], $orig->[$i]);
 687         }
 688         $REFS{$id}{Hash::Util::FieldHash::id($orig)} = $self;
 689     }
 690     elsif (is_plain_hashref($orig) || (blessed $orig && $orig->isa(__PACKAGE__))) {
 691         for my $key (keys %$orig) {
 692             _save_references($id, $self->{$key}, $orig->{$key});
 693         }
 694         $REFS{$id}{Hash::Util::FieldHash::id($orig)} = $self;
 695     }
 696 }
 697
 698 # During a rollback, copy data from the snapshot back into the original internal structures.
 699 sub _restore_references {
 700     my $id   = shift;
 701     my $orig = shift // return;
 702     my $self = delete $REFS{$id}{Hash::Util::FieldHash::id($orig) // ''} // return $orig;
 703
 704     if (is_plain_arrayref($orig)) {
 705         @$self = map { _restore_references($id, $_) } @$orig;
 706     }
 707     elsif (is_plain_hashref($orig) || (blessed $orig && $orig->isa(__PACKAGE__))) {
 708         for my $key (keys %$orig) {
 709             # next if is_ref($orig->{$key}) &&
 710             #     (Hash::Util::FieldHash::id($self->{$key}) // 0) == Hash::Util::FieldHash::id($orig->{$key});
 711             $self->{$key} = _restore_references($id, $orig->{$key});
 712         }
 713     }
 714
 715     return $self;
 716 }
 717
 718 ##############################################################################
 719
 720 sub _signal {
 721     my $self = shift;
 722     my $type = shift;
 723
 724     if ($self->_in_txn) {
 725         my $stack = $self->_signal_stack;
 726         my $queue = $stack->[-1];
 727         push @$queue, [$type, @_];
 728     }
 729
 730     $self->_signal_send([[$type, @_]]);
 731
 732     return $self;
 733 }
 734
 735 sub _signal_stack { $SIGNALS{$_[0]} //= [] }
 736
 737 sub _signal_begin_work {
 738     my $self = shift;
 739     push @{$self->_signal_stack}, [];
 740 }
 741
 742 sub _signal_commit {
 743     my $self = shift;
 744     my $signals = pop @{$self->_signal_stack};
 745     my $previous = $self->_signal_stack->[-1] // [];
 746     push @$previous, @$signals;
 747     return $previous;
 748 }
 749
 750 sub _signal_rollback {
 751     my $self = shift;
 752     pop @{$self->_signal_stack};
 753 }
 754
 755 sub _signal_send {
 756     my $self    = shift;
 757     my $signals = shift // [];
 758
 759     my $kdbx = $KDBX{$self} or return;
 760
 761     # de-duplicate, keeping the most recent signal for each type
 762     my %seen;
 763     my @signals = grep { !$seen{$_->[0]}++ } reverse @$signals;
 764
 765     for my $sig (reverse @signals) {
 766         $kdbx->_handle_signal($self, @$sig);
 767     }
 768 }
 769
 770 ##############################################################################
 771
 772 sub _wrap_group {
 773     my $self  = shift;
 774     my $group = shift;
 775     require File::KDBX::Group;
 776     return File::KDBX::Group->wrap($group, $KDBX{$self});
 777 }
 778
 779 sub _wrap_entry {
 780     my $self  = shift;
 781     my $entry = shift;
 782     require File::KDBX::Entry;
 783     return File::KDBX::Entry->wrap($entry, $KDBX{$self});
 784 }
 785
 786 sub TO_JSON { +{%{$_[0]}} }
 787
 788 1;
 789 __END__
 790
 791 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
 792
 793 =head1 DESCRIPTION
 794
 795 KDBX is an object database. This abstract class represents an object. You should not use this class directly
 796 but instead use its subclasses:
 797
 798 =for :list
 799 * L<File::KDBX::Entry>
 800 * L<File::KDBX::Group>
 801
 802 There is some functionality shared by both types of objects, and that's what this class provides.
 803
 804 Each object can be connected with a L<File::KDBX> database or be disconnected. A disconnected object exists in
 805 memory but will not be persisted when dumping a database. It is also possible for an object to be connected
 806 with a database but not be part of the object tree (i.e. is not the root group or any subroup or entry).
 807 A disconnected object or an object not part of the object tree of a database can be added to a database using
 808 one of:
 809
 810 =for :list
 811 * L<File::KDBX/add_entry>
 812 * L<File::KDBX/add_group>
 813 * L<File::KDBX::Group/add_entry>
 814 * L<File::KDBX::Group/add_group>
 815 * L<File::KDBX::Entry/add_historical_entry>
 816
 817 It is possible to copy or move objects between databases, but B<DO NOT> include the same object in more
 818 than one database at once or there could be some strange aliasing effects (i.e. changes in one database might
 819 effect another in unexpected ways). This could lead to difficult-to-debug problems. It is similarly not safe
 820 or valid to add the same object multiple times to the same database. For example:
 821
 822     my $entry = File::KDBX::Entry->(title => 'Whatever');
 823
 824     # DO NOT DO THIS:
 825     $kdbx->add_entry($entry);
 826     $another_kdbx->add_entry($entry);
 827
 828     # DO NOT DO THIS:
 829     $kdbx->add_entry($entry);
 830     $kdbx->add_entry($entry); # again
 831
 832 Instead, do this:
 833
 834     # Copy an entry to multiple databases:
 835     $kdbx->add_entry($entry);
 836     $another_kdbx->add_entry($entry->clone);
 837
 838     # OR move an existing entry from one database to another:
 839     $another_kdbx->add_entry($entry->remove);
 840
 841 =attr uuid
 842
 843 128-bit UUID identifying the object within the connected database.
 844
 845 =attr icon_id
 846
 847 Integer representing a default icon. See L<File::KDBX::Constants/":icon"> for valid values.
 848
 849 =attr custom_icon_uuid
 850
 851 128-bit UUID identifying a custom icon within the connected database.
 852
 853 =attr tags
 854
 855 Text string with arbitrary tags which can be used to build a taxonomy.
 856
 857 =attr previous_parent_group
 858
 859 128-bit UUID identifying a group within the connected database the previously contained the object.
 860
 861 =attr last_modification_time
 862
 863 Date and time when the entry was last modified.
 864
 865 =attr creation_time
 866
 867 Date and time when the entry was created.
 868
 869 =attr last_access_time
 870
 871 Date and time when the entry was last accessed.
 872
 873 =attr expiry_time
 874
 875 Date and time when the entry expired or will expire.
 876
 877 =attr expires
 878
 879 Boolean value indicating whether or not an entry is expired.
 880
 881 =attr usage_count
 882
 883 The number of times an entry has been used, which typically means how many times the B<Password> string has
 884 been accessed.
 885
 886 =attr location_changed
 887
 888 Date and time when the entry was last moved to a different parent group.
 889
 890 =cut